Skip to main content
Mapagam

Working with Container Registry

1. Authenticating to Registry

Method Description Configuration Notes
CI_REGISTRY_USER Username for registry authentication CI_REGISTRY_USER Automatically set by GitLab CI/CD
CI_REGISTRY_PASSWORD Password for registry authentication CI_REGISTRY_PASSWORD Automatically set by GitLab CI/CD
CI_REGISTRY Registry URL CI_REGISTRY Automatically set by GitLab CI/CD

Example: Using Registry Credentials in a Job

build_job:
  image: alpine:latest
  script:
    - echo "Building image..."
    - docker build -t $CI_REGISTRY_IMAGE .
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
    - docker push $CI_REGISTRY_IMAGE
Note: The CI_REGISTRY_USER and CI_REGISTRY_PASSWORD are automatically provided by GitLab CI/CD for the project's container registry.
Warning: Never expose CI_REGISTRY_PASSWORD in logs or output. GitLab CI/CD automatically masks secrets.

2. Using CI_REGISTRY Variables

Variable Description Usage
CI_REGISTRY URL of the GitLab Container Registry docker build -t $CI_REGISTRY/image-name .
CI_REGISTRY_USER Username for pushing to the registry docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
CI_REGISTRY_PASSWORD Password for pushing to the registry docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
CI_REGISTRY_IMAGE Full image name including registry URL docker push $CI_REGISTRY_IMAGE

Example: Pushing an image to GitLab Container Registry

docker build -t $CI_REGISTRY_IMAGE .
docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
docker push $CI_REGISTRY_IMAGE

3. Building and Pushing Images

Option Values Description
image.name my-app:latest Name of the Docker image to build and push
image.registry registry.gitlab.com Registry URL to push the image to
image.tag $CI_COMMIT_SHORT_SHA Tag to use for the image (e.g., commit SHA or custom tag)

Example: Building and Pushing an Image

build_image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
Note: Ensure that the docker:dind service is used to run Docker-in-Docker for building images.
Warning: Make sure the CI_REGISTRY_IMAGE variable is set correctly in your GitLab project settings.

4. Tagging Images ($CI_COMMIT_REF_SLUG)

Property Description Value
CI_COMMIT_REF_SLUG Slugified version of the branch or tag name $CI_COMMIT_REF_SLUG

Example: Using $CI_COMMIT_REF_SLUG in Dockerfile

FROM alpine:latest
LABEL version="$CI_COMMIT_REF_SLUG"
RUN echo "Building image for branch/tag: $CI_COMMIT_REF_SLUG"

Example: Using $CI_COMMIT_REF_SLUG in GitLab CI/CD Pipeline

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t my-app:$CI_COMMIT_REF_SLUG .
    - docker push my-app:$CI_COMMIT_REF_SLUG

5. Using Multi-Architecture Images

Multi-architecture images allow you to build and push images that can run on different CPU architectures (e.g., amd64, arm64) from a single GitLab CI/CD pipeline.

Architecture Description Support Status
amd64 Standard x86_64 architecture SUPPORTED
arm64 ARM 64-bit architecture (e.g., Apple Silicon, Raspberry Pi) SUPPORTED
arm/v7 ARM 32-bit architecture (older ARM devices) LIMITED

Example: Building Multi-Architecture Images with Docker Buildx

docker buildx create --name mybuilder --use
docker buildx build --platform linux/amd64,linux/arm64 -t myregistry/myapp:latest .
Note: Ensure that your GitLab Runner has docker buildx support enabled.

Key Points

  • Use docker buildx to build multi-architecture images.
  • Specify platforms using --platform flag.
  • Push images to a container registry that supports multi-arch manifests.

6. Scanning Container Images

Option Values Description
image_scanning true Enable image scanning for container images
scan_on_push false Scan images immediately after pushing to registry
vulnerability_scanning true Enable vulnerability scanning in GitLab CI/CD

Example: Enable image scanning in GitLab CI/CD

scan_image:
  stage: scan
  image: <registry-url>/gitlab/dependency-scanning:latest
  script:
    - echo "Scanning image for vulnerabilities"
    - gitlab-dependency-scanning --image <image-name>
Note: GitLab CI/CD supports integration with Trivy and Clair for scanning container images.
Warning: Ensure that the image scanning job runs in a secure environment to avoid exposing sensitive data.
Scan Type Description Tool Used Status
Dependency Scanning Scans for known vulnerabilities in dependencies Trivy, Clair NEW
Container Image Scanning Scans container images for vulnerabilities Trivy, Clair NEW

7. Cleaning Up Old Images

Option Values Notes
container_registry.cleanup_policies enabled Enable cleanup policies for container images
container_registry.max_days_to_keep 30 Maximum days to keep images before deletion
container_registry.max_images_to_keep 10 Maximum number of images to keep per tag

Example: Configure Cleanup Policy in .gitlab-ci.yml

stages:
  - build
  - cleanup

build_job:
  stage: build
  image: alpine:latest
  script:
    - echo "Building image..."
  artifacts:
    paths:
      - build/

cleanup_job:
  stage: cleanup
  image: registry.gitlab.com/gitlab-org/container-registry:latest
  script:
    - echo "Cleaning up old images..."
    - /usr/bin/container-registry cleanup --max-days=30 --max-images=10
Note: Cleanup policies are applied at the project level and can be configured via GitLab UI or API.
Warning: Ensure that cleanup policies do not interfere with running services or critical builds.

8. Using Registry API

Endpoint Method Description Notes
/projects/:id/registry/repositories GET Get list of container repositories Requires read_registry permission
/projects/:id/registry/repositories/:repository_id GET Get specific repository details
/projects/:id/registry/repositories/:repository_id/tags GET List tags for a repository
/projects/:id/registry/repositories/:repository_id/tags/:tag_name DELETE Delete a specific tag

Example: Fetching Registry Repositories

curl --header "PRIVATE-TOKEN: glpat-xxxxxxxx" \
  "https://gitlab.example.com/api/v4/projects/123/registry/repositories"

Example: Deleting a Tag

curl --request DELETE \
  --header "PRIVATE-TOKEN: glpat-xxxxxxxx" \
  "https://gitlab.example.com/api/v4/projects/123/registry/repositories/456/tags/v1.0.0"
Note: The Registry API is available in GitLab Premium and above. Access tokens must have read_registry or write_registry scope.

9. Configuring Registry Mirrors

Example: Configure registry mirror in GitLab CI

variables:
  DOCKER_REGISTRY_MIRROR: "https://mirror.gcr.io"

services:
  - name: registry:2
    alias: registry-mirror
    command: ["registry", "serve", "/etc/registry/config.yml"]

before_script:
  - echo "Registry mirror configured"
Property Description Default Notes
CI_REGISTRY_MIRROR Mirror URL for GitLab Container Registry None Used to pull images from a mirrored registry
DOCKER_REGISTRY_MIRROR Registry mirror URL for Docker images None Can be set to a local or external registry mirror
Note: Registry mirrors are useful for improving image pull performance and reducing bandwidth usage in CI/CD pipelines.
Warning: Ensure that the mirror URL is accessible and properly configured to avoid pipeline failures.

Configuration Summary

  • Set CI_REGISTRY_MIRROR to point to a mirrored registry
  • Use DOCKER_REGISTRY_MIRROR for Docker image mirrors
  • Ensure mirror is accessible from CI runner environment

10. Implementing Image Signing

Property Description Values
image.signing.enabled Enables image signing in the container registry true / false
image.signing.key Path to the signing key file in the GitLab runner path/to/signing/key
image.signing.algorithm Algorithm used for signing (e.g., ecdsa, rsa) ecdsa, rsa

Example: Enable image signing in a GitLab CI job

job_name:
  image: alpine:latest
  script:
    - echo "Building and signing image"
    - docker build -t my-image .
    - docker tag my-image registry.gitlab.com/group/project/my-image:latest
    - cosign sign --key /path/to/key registry.gitlab.com/group/project/my-image:latest
Note: Image signing requires cosign or similar tools to be installed in the runner environment.
Warning: Ensure that signing keys are securely stored and not exposed in CI configuration files.

Was this article helpful?

Related Cheat Sheets