Improve this page on GitHub

Docker registries for pipeline integrations

Connect your Docker Registry to Codefresh CI pipelines

Codefresh enables you to integrate with several Docker container registries, including (but not limited to):

For a different registry, choose to configure using the Other option.

The registries can either be public or private.

General Configuration

IMPORTANT
The name assigned to the integration must be unique within the account. Using the same name for other integrations or Shared Configuration contexts within pipelines will result in conflicts.
For troubleshooting, see Error: context already exists.

  1. In the Codefresh UI, on the toolbar, click the Settings icon, and then from the sidebar, select Pipeline Integrations.
  2. Select Docker Registries and then click Configure.

Codefresh Account Integration

  1. From the Add Registry Provider drop-down, select the regsitry type to add.

Add Docker Registry

  1. Each configuration must be given a unique name, which you can later reference in a codefresh.yml file.

Define fallback registry

Codefresh has a feature that allows users to designate a fallback registry for Docker integrations. If a Codefresh pipeline attempts to pull an image and that image fails for any reason (authorization issue, the registry server is down, etc.), a retry mechanism will attempt to pull it successfully. If this mechanism fails, the fallback registry feature provides the opportunity to pull the image from a different registry you have specified.

  1. In the Codefresh UI, on the toolbar, click the Settings icon, and then from the sidebar, select Pipeline Integrations.
  2. Select Docker Registries and then click Configure.
  3. In the list of registries, select the registry to configure as the fallback registry, and click Edit.
  4. Expand Advanced Options, and select the registry from the Fallback Registry list.
    You can also specify a fallback registry when creating a new integration as long as another integration exists.

Using an optional repository prefix

For each supported Registry, define a prefix string for your Docker images to be used globally.

This is handy for registries that require a prefix (usually the name of an organization or repository) as you can set it once, instead of having each pipeline using the prefix by itself.

Setting a Registry prefix

Setting a Registry prefix

See more details at pushing Docker images.

Pushing an image

Once your registry configuration is all set up you can start pushing your images to it.

Within a push step, add your registry configuration name in the registry field

codefresh.yml

push_step:
  type: push
  description: Free text description
  candidate: ${{build_step}}
  tag: ${{CF_BRANCH}}
  registry: your-registry-configuration-name

For more details, see the example for image push.

Internal caching registry

You can also select a single registry that will serve as your caching registry.

NOTE
You cannot select Dockerhub as a caching registry, because it has very strict requirements for naming images, and our caching mechanism needs capabilities which are not possible with Dockerhub.

Codefresh uses that registry efficiently to perform advanced caching logic for your builds by automatically:

  • Checking the stored metadata to decide which past image is most relevant for caching purposes
  • Pulling images from this registry for caching purposes
  • Using that registry for distributed Docker layer caching to make your Docker builds faster

We give you the ability to define a separate registry for caching purposes for the following scenarios:

  1. You don’t want extra traffic to be sent to your main deployment registry. Maybe you want to avoid bandwidth/storage limits in your production registry
  2. You have lots of build steps in pipelines with intermediate docker images that you are certain you don’t need outside of the pipeline itself. In that case you can use the disable_push property in those pipelines.
  3. You have speed concerns regarding image pulling/pushing. For example your development team is in Europe, but your production servers are in the USA. You would probably choose a caching registry in a European region (so that developers get the best experience), where your main registry is in the USA (close to your production servers)

Therefore, in most cases you should make your main registry your caching registry as well. For extra control, you can either define a different caching registry or disable selectively automatic pushes with the disable_push property.

NOTE
The dynamic image feature of Codefresh (creating docker images on demand in the same pipeline that is using them) will always work regardless of a caching registry.

Default registry

If you define more than one registry, you can select a registry as the default one. Codefresh uses the default registry in both build and push steps if they don’t already include a registry property.

NOTE
Successful build steps always push to the default Codefresh registry, unless you also define the disable_push property.

  1. In the Codefresh UI, on the toolbar, click the Settings icon, and then from the sidebar, select Pipeline Integrations.
  2. Select Docker Registries and then click Configure.
  3. From the context menu of the Docker registry integration to be used as the default registry, select Set as default.

Examples of pushing Docker images