# GitLab CI (https://depot.dev/docs/container-builds/integrations/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](/docs/cli/authentication#project-tokens)

A project access token can be injected into your GitLab job for `depot` CLI authentication via [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/) or [external secrets](https://docs.gitlab.com/ee/ci/secrets/). Project tokens are tied to a specific project in your organization and not a user.

### [User access token](/docs/cli/authentication#user-access-tokens)

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](https://docs.gitlab.com/ee/ci/variables/) or [external secrets](https://docs.gitlab.com/ee/ci/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](https://docs.gitlab.com/ee/ci/variables/index.html). We recommend using a [project token](/docs/cli/authentication#project-tokens).

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

```yaml showLineNumbers
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](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#determine-your-docker_auth_config-data)) to inject a [GitLab Deploy Token](https://docs.gitlab.com/ee/user/project/deploy_tokens/) 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.

```yaml showLineNumbers
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](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-in-docker-executor) 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.

```yaml showLineNumbers
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.

```yaml showLineNumbers
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.

```yaml showLineNumbers
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.

```yaml showLineNumbers
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
```

## For AI Agents

The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.