Backend: Identify docker image as build artifact for specific pipeline

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Status Update (15th Sept 2025)

We currently recommend using GitLab's Container Registry - #18264 (comment 2748559905) and are not planning any specific work related to tying pipeline and docker images. We'd love to know your feedback on the recommendation. Please leave a comment on this thread

Description

We track file-based artifacts, but increasingly the result of a CI/CD's "build" stage is actually a Docker image. We should have some way of identifying that a specific docker image is the actual build artifact for a given pipeline.

Proposal

Incomplete proposal:

build:
  artifacts:
    image: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Note that it would be awesome if we didn't need to actually push the artifact to the registry to declare it as a build artifact. So maybe being able to build it locally, and then just declare the local image as the build artifact would let us carry it forward to subsequent pipeline jobs, and to publish to the registry if needed. For example, some build artifacts can be thrown away and don't need to be published, but others get promoted to higher status. We don't currently let you differentiate these two use-cases with artifacts, but we should, and they especially apply to docker images that would otherwise clutter the registry. Of course, an artifact expiry might be sufficient here as well.

So a better flow would be:

build:
  script:
    - docker build -t temp .
  artifacts:
    image: temp

which would then take the image from the local docker daemon and publish to the registry for you. Any subsequent job that depends on it would have the image pre-pulled into the docker daemon. With sticky runners, we could shortcut that and just rely on a persistent daemon. We'd have to be very careful to make sure that the right image is used, so when it's put into the registry, it would likely be tagged with the pipeline ID (or git SHA, or both). But that could be transparent to the user.

Lastly, it kinda sucks to have to know the name of the image ahead of time. But I don't see any reasonable way to build an untagged image and then capture the image SHA and pass to the artifact declaration. Hopefully this isn't necessary.

Links / references

Documentation blurb

(Write the start of the documentation of this feature here, include:

  1. Why should someone use it; what's the underlying problem.
  2. What is the solution.
  3. How does someone use this

During implementation, this can then be copied and used as a starter for the documentation.)

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by 🤖 GitLab Bot 🤖