What are the best practices (if any) for coupling a docker image registry with a SCM service (such as bitbucket)?

I know a docker registry can live in artifactory, but how can I assure that the two are as tightly coupled as possible?

For example I am worried that without due-diligence from developers the latest Docker image in the registry will not reflect the current state of the Dockerfile in SCM or vice-versa. Also it is imperative that we can always trace back to the base Dockerfile (that we made) for any image in the registry.

2 Answers 2


If you want a beautiful integration between Docker and SCM, GitLab provides it's own built-in Docker registry. This makes publishing a Docker image in the build pipeline a breeze.

The other big advantage of GitLab Docker registry is that it supports multiple Docker repositories for each GitLab repo. This allows you to create a new Docker repo for each branch, or each commit, each environment, or anything you need.

My company leverages this by pushing our images to repos based on the branch, tagged with their commit. Here is an example: project-name/branch-name:commit-SHA

Or if you have multiple Docker images being build for a particular branch (like a front-end Angular app and it's back-end API that it talks to), you can scope it even further, like so:

There are no limits to the number of slashes (/) you can use for scoping. This makes it very easy to tell the exact commit of an image when it's deployed. For this reason, my company almost never uses the generic 'latest' tag. We prefer the specificity of which image is deployed where.

You can still apply this same 'multiple docker repo' logic to any Docker registry. You'll have to look up that specific system's capabilities for creating new repos on the fly, and how easy it is to integrate with your CI/CD pipeline.

  • 1
    FYI Docker Public registry recommends 2 slash-separated components, see PATH: docs.docker.com/engine/reference/commandline/tag/#description Some public registries only support 2 slash-separated components. Apparently the spec does not impose a limit. We're using Sonatype Nexus Repository, which does support more than 2 slash-separated components, so for a private repo, you can certainly do this.
    – ptha
    Commented Sep 7, 2023 at 8:25

I was able to get an answer over here forums.docker.com Credit goes to dmaze.

Set up some sort of automated build system (“continuous integration” in the current trendy term). Docker is sufficiently mainstream at this point that any of the cloud-based or locally-installed CI systems can do it.

In your Dockerfile, use a LABEL to record the source of the build. That probably includes the commit hash from distributed source control (git, Mercurial), the branch name if relevant, any release tags if present, and possibly details like the timestamp of the last commit. docker history and docker inspect should be able to show these.

When you docker push your images, push them at least twice, with the commit hash and with the branch name as the “version” part (quay.io/mycorp/imagename:123abc7, quay.io/mycorp/imagename:dmaze-test). If release tags are readily available, the CI system should push images with these tags too.

Make sure the Dockerfile is committed to source control, of course, and try to have a stable path to get any external dependencies that may be present.

Now you can go both ways: given an arbitrary commit, if your CI system built it, you can docker run the image it built; and if you have an image, you can find where exactly in source history it came from, and git checkout or hg up to that specific version, and docker build a near-identical copy of it yourself.

  • Is there a difference when pushing docker multiple times?
    – Moritz
    Commented Feb 14, 2018 at 23:23
  • not sure of your question but the docker registry will keep track of the image's hash so if you push a docker image multiple times (with different tags) you will get multiple 'image names' with the tags but they all reference the same hash.. so no extra space is taken except that to store the new image name.
    – scott
    Commented Feb 15, 2018 at 21:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.