Working with Docker Registries
How to push, pull and tag Docker images in Codefresh pipelines
Codefresh contains first class Docker registry support. This means that you don’t need to manually write
docker login and
docker pull/push commands inside pipelines. You use instead declarative YAML and all credential configuration is configured centrally once.
Viewing Docker images
To see all images currently from all your connected Registries, select Artifacts -> Images from the left sidebar and you will see a sorted list of all images.
For each image you get some basic details such as the git branch, commit message and hash that created it, date of creation as well as all tags. You can click on any image and look at its individual metadata.
On the top left of the screen you can find several filters that allow you to search for a specific subset of Docker images:
- Tagged/untagged images
- Base image name
- Git branch
- Pipeline volumes
You can add multiple filters and they will work in an
On the right side of the screen you also have a list of buttons for actions on each Docker image. These are:
- Launching a Docker image as a test environment
- Promoting a Docker image (explained in the following sections)
- Looking at the docker commands that allow you to pull the image locally on your workstation
- Re-running the pipeline that created this image
Pulling Docker images
Pulling Docker images in Codefresh is completely automatic. You only need to mention a Docker image by name and Codefresh will automatically pull it for you and use it in a pipeline.
Pulling public images
To pull a public image from Dockerhub or other public registry you simply mention the name of the image and tag that you want to use. For example:
CollectAllMyDeps: title: Install dependencies image: python:3.6.4-alpine3.6 commands: - pip install .
The image will also be cached in the image cache without any other configuration.
Codefresh will also automatically pull for you any images mentioned in Dockerfiles (i.e. the
FROM directive) as well as service containers.
Pulling private images
To pull a private image from one of your connected registries, again you mention the image by name and tag. In order for Codefresh to understand that you are talking about a private image you need to prepend the appropriate prefix of the registry domain.
For example in the case of ACR:
You can find the full name of any docker image by visiting the image dashboard and looking at the URL field of any tag:
The exact format of the full image name will depend on the type of registry you use. Codefresh will use the domain prefix of each image to understand which integration it will use. It will then take care of all
docker login and
docker pull commands on its own behind the scenes.
Codefresh will automatically login to each registry using the credentials you have defined centrally and pull all the images. The same thing will happen with Dockerfiles that mention any valid docker image in their
Pulling images that were just built in the same pipeline
Codefresh allows you to create a docker image on demand and use it in the same pipeline that created it. In several scenarios (such as unit tests) it is very common to use a Docker image right after it was built.
In this pipeline Codefresh:
- Checks out source code with the git-clone step
- Builds a docker image that gets named
my-app-image:master. Notice the lack of
- In the next step automatically uses that image and runs
python setup.py testinside it. Again notice the lack of
The important line here is the following:
This says to Codefresh “in this step please use the Docker image that was built in the step named
You can see the automatic pull inside the Codefresh logs.
The image will still be pushed in your default Docker registry. If you don’t want this behavior you can simply add the
disable_push property in the build step.
Pushing Docker images
Pushing to your default Docker registry is completely automatic. All successful build steps automatically push to the default Docker registry of your Codefresh account without any extra configuration.
To push to another registry you only need to know how this registry is linked into Codefresh and more specifically what is unique name of the integration. You can see that name by visiting your integrations screen or asking your Codefresh administrator.
candidatefield of the push step mentions the name of the build step (
build_image) that will be used for the image to be pushed
- The registry is only identified by name (i.e.
azure-demo). The domain and credentials are not part of the pipeline (they are already known to Codefresh by the Docker registry integration)
You can also override the name of the image with any custom name. This way the push step can choose any image name regardless of what was used in the build step.
Here the build step is creating an image named
my-app-image:master but the push step will actually push it as
For more examples such as using multiple tags, or pushing in parallel see the push examples
Promoting Docker images
Apart from building and pushing a brand new docker image, you can also “promote” a docker image by copying it from one registry to another. You can perform this action either from the Codefresh UI or automatically from pipelines.
Promoting images via the Codefresh UI
You have the capability to “promote” any image of your choosing and push it to an external Registry that you have integrated into Codefresh (such as Azure, Google, Bintray etc)
Visit the Docker image dashboard and click the Promote button for the image you wish to promote:
You will get a list of your connected registries. Choose the target Registry and define the tag that you want to push. Then click the Promote button to “copy” this image from its existing registry to the target Registry.
Promoting images in pipelines
You can also copy images from one registry to the other inside a pipeline.
This is accomplished by specifying an existing image in the
candidate field of the push step.
You can even “promote” docker images within the same registry by simply creating new tags. For example:
In the example above the image
my-azure-registry.azurecr.io/kostis-codefresh/my-python-app:1.2.3 is re-tagged as
my-azure-registry.azurecr.io/kostis-codefresh/my-python-app:prod. A very common pattern is to mark images with a special tag such as
prod after the image has been deployed successfully.