We use cookies to understand how people use Depot.
Depot
Sign InStart for free
Container Builds

GitLab CI

Authentication

For GitLab, you can use project or user access tokens for authenticating your build with Depot. We recommend using project tokens as they are scoped to the specific project and are owned by the organization.

Project token

A project access token can be injected into your GitLab job for depot CLI authentication via CI/CD variables or external secrets. Project tokens are tied to a specific project in your organization and not a user.

User access token

It is also possible to generate a user access token that can be injected into your GitLab job for depot CLI authentication via CI/CD variables or external secrets. User tokens are tied to a specific user and not a project. Therefore, it can be used to build all projects across all organizations the user can access.

Configuration

To build a Docker image from GitLab, you must set the DEPOT_TOKEN environment variable in your CI/CD settings for your repository. You can do this through the UI for your repository via this documentation. We recommend using a project token.

In addition, you must also install the depot CLI before you run depot build.

build-image:
  before_script:
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
  script:
    - depot build .
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN

Examples

Build and push to GitLab registry

To build a Docker image from GitLab and push it to a registry, you have two options to choose from because of how GitLab CI/CD with Docker allows you to build Docker images.

Option 1: Use the DOCKER_AUTH_CONFIG variable

This example demonstrates how you can use the CI/CD variable DOCKER_AUTH_CONFIG (see these docs) to inject a GitLab Deploy Token you have created that can read/write to the GitLab registry.

You then inject that file before the build, which allows depot build . --push to authenticate to your registry.

Note: This requires configuring an additional CI/CD variable, but it avoids using Docker-in-Docker.

build-image:
  before_script:
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
    - mkdir -p $HOME/.docker
    - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json
  script:
    - depot build -t registry.gitlab.com/repo/image:tag . --push
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN

Option 2: Using Docker-in-Docker

This example demonstrates using the Docker-in-Docker executor. This method allows you to install the depot CLI in the before_script block and use docker login to authenticate to whichever registry you use.

image: docker:20.10.16
services:
  - docker:20.10.16-dind
variables:
  DOCKER_HOST: tcp://docker:2376
  DOCKER_TLS_CERTDIR: '/certs'
 
build-image:
  before_script:
    - apk add --no-cache curl
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
  script:
    - echo "$DOCKER_REGISTRY_PASS" | docker login registry.gitlab.com --username <your-username> --password-stdin
    - depot build --project <your-project-id> -t registry.gitlab.com/repo/image:tag . --push
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN

Build multi-platform images natively without emulation

This example shows how you can use the platforms flag to build a multi-platform image for Intel and Arm architectures natively without emulation.

build-image:
  before_script:
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
    - mkdir -p $HOME/.docker
    - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json
  script:
    - depot build -t registry.gitlab.com/repo/image:tag --platform linux/amd64,linux/arm64 . --push
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN

Export an image to Docker

By default, like docker buildx, Depot doesn't return the built image to the client. However, for cases where you need the built image in your GitLab workflow, you can pass the --load flag, and Depot will return the image to the workflow.

build-image:
  before_script:
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
    - mkdir -p $HOME/.docker
    - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json
  script:
    - depot build -t your-tag --load .
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN

Build an image with Software Bill of Materials

Build an image with a Software Bill of Materials (SBOM) using the --sbom and --sbom-dir flags. The sbom flag will generate an SBOM for the image, and the sbom-dir flag will output the SBOM to the specified directory.

build-image:
  before_script:
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
    - mkdir -p $HOME/.docker
    - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json
  script:
    - depot build -t your-tag --sbom=true --sbom-dir=sboms .
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN