What is Docker Image Promotion and Why Should I Use It?

Docker Image Promotion is the process of promoting Docker Images between registries to ensure that only approved and verified images are used in the right environments, such as production.

In ProGet, images can be promoted from one registry to another and tracked throughout the process. This allows you to build a promotion pipeline that allows you to maintain separate levels of quality in different registries (such as Development, Production, etc).

How to Promote an Image

There are two ways to promote an image, using the Promote button on the repository's tag page in ProGet or an API call. Any images that are promoted to a target registry are not deleted from the source registry.

Currently, images that use "fat" manifests cannot be promoted. You will need to recreate and push those images through the docker CLI to your target registry.

Creating a Validated/Promoted Docker Registry

Any registry can be used as a validated/promoted Docker registry, but best practice is to create a separate registry that contains only promoted internal images and verified external images. When creating your new Docker registry, select the validated/promoted feed usage type.

Promoting Images Using The Repository's Tag Page

To promote an image using the repository's tag page, first navigate to the registry, repository, and tag you would like to promote. Hover over the ▼-button in the upper right corner, and click the Promote button.

Promoting Images Using API

To promote an image via the API you will first need to generate an API key that grants access to Package Promotion. Then visit our Package Promotion Endpoint guide in our ProGet API Reference section to familiarize yourself on how to work with ProGet APIs and the Promote Packages endpoint.

Creating an Image Promotion Pipeline

An image promotion pipeline helps you to enforce the process of elevating images between your different registries/environments by selecting a specific target registry. Once a target registry is selected to promote to, both the repository's tag page and the Package Promotion Endpoint will only allow you to promote images to the selected target registry.

To configure the pipeline, you will need to:

1. Navigate to the source registry containing the images to be promoted
2. Click on the Manage Feed button in the upper right corner of the page
3. Click the configure link to the right of the Promote To Feed property
4. Select the target promotion registry

Note: A validated/promoted Docker registry can be a source registry for a different validated/promoted Docker registry. This allows you to keep environments separated into different registries and enforce an elevation process across registries.

Package Promotion Security

Promote Packages is a built-in task in ProGet. This task allows access to promote images to a specified registry. Users granted this task should also be granted at least the View & Download Packages task for the source registry.

You can also create a Custom Task by going to Administration > Users & Tasks > Customize Tasks. To give or deny users/groups permissions to this task go to the Users & Tasks page.

Track Your Image Promotions

Image promotion tracking is viewable in the History tab on the repository's tag page. The history will show a Promoted action that includes:

• When the promotion occurred
• Who promoted the image
• The source registry
• The target registry
• Any comments left by the promoter