Skip to main content

GitLab CI

GitLab CI runs dagger check inside your existing pipeline, so the same checks you run locally run on every push — without rewriting your .gitlab-ci.yml.

tip

For checks with no pipeline YAML at all, enable Cloud Checks with dagger ws autocheck on. The GitLab CI configuration below is the hybrid-mode alternative for when you want to drive Dagger from your existing GitLab CI setup.

How it works​

When running your Dagger checks with GitLab CI, the general workflow looks like this:

  1. GitLab receives a trigger based on a repository event.
  2. GitLab begins processing the stages and jobs in the .gitlab-ci.yml file.
  3. GitLab downloads the Dagger CLI.
  4. GitLab runs dagger check against the modules installed in your workspace.
  5. The Dagger CLI attempts to find an existing Dagger Engine or spins up a new one inside the GitLab runner.
  6. The Dagger CLI runs the checks and sends telemetry to Dagger Cloud if the DAGGER_CLOUD_TOKEN environment variable is set.
  7. The pipeline completes with success or failure based on the check results. Logs appear in GitLab as usual.

Prerequisites​

Examples​

Docker executor​

The following example demonstrates how to run dagger check in a GitLab CI/CD pipeline using the (default) Docker Machine executor or the Docker executor. In both these cases, the Dagger Engine is provisioned "just in time" using a Docker-in-Docker (dind) service.

.gitlab-ci.yml
.docker:
  image: docker:latest
  services:
    - docker:${DOCKER_VERSION}-dind
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_VERIFY: '1'
    DOCKER_TLS_CERTDIR: '/certs'
    DOCKER_CERT_PATH: '/certs/client'
    DOCKER_DRIVER: overlay2
    DOCKER_VERSION: '27.2.0'
    # assumes the Dagger Cloud token is
    # in a masked/protected variable named DAGGER_CLOUD_TOKEN
    # set via the GitLab UI
    DAGGER_CLOUD_TOKEN: $DAGGER_CLOUD_TOKEN
.dagger:
  extends: [.docker]
  before_script:
    - apk add curl
    - curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=/usr/local/bin sh
check:
  extends: [.dagger]
  script:
    - dagger check

dagger check runs all checks from the modules installed in your workspace and exits non-zero if any fail. To scope the run to a single module's checks, pass a pattern — for example dagger check go:*.

Kubernetes executor​

The following example demonstrates how to run dagger check in a GitLab CI/CD pipeline using the Kubernetes executor.

.gitlab-ci.yml
.dagger:
  image: alpine:latest
  variables:
    # assumes the Dagger Cloud token is
    # in a masked/protected variable named DAGGER_CLOUD_TOKEN
    # set via the GitLab UI
    DAGGER_CLOUD_TOKEN: $DAGGER_CLOUD_TOKEN
  before_script:
    - apk add curl
    - curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=/tmp sh
check:
  extends: [.dagger]
  script:
    - dagger check

Each GitLab Runner must be configured to only run on nodes with pre-provisioned instances of the Dagger Engine. This is achieved using taints and tolerations on the nodes, and pod affinity.

The following code listings illustrate the configuration to be applied to each GitLab Runner, with taints, tolerations and pod affinity set via the dagger-node key. For an example of the corresponding node configuration, refer to the OpenShift integration page.

To use this configuration, replace the YOUR-GITLAB-URL placeholder with the URL of your GitLab instance and replace the YOUR-GITLAB-RUNNER-TOKEN-REFERENCE placeholder with your GitLab Runner authentication token.

runner-config.yml
kind: ConfigMap
apiVersion: v1
metadata:
  name: dagger-custom-config-toml
data:
  config.toml: |
    concurrent = 10
    [[runners]]
      environment = ["HOME=/tmp","FF_GITLAB_REGISTRY_HELPER_IMAGE=1", "_EXPERIMENTAL_DAGGER_RUNNER_HOST=unix:///run/dagger/engine.sock"]
      pre_build_script = "export PATH=\"/tmp/:$PATH\""
      name = "GitLab Runner with Dagger"
      url = YOUR-GITLAB-URL
      executor = "kubernetes"
      [runners.kubernetes]
        namespace = "dagger"
        pull_policy = "always"
        privileged = true
      [runners.kubernetes.affinity]
      [runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution]
        [[runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms]]
          [[runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms.match_expressions]]
            key = "dagger-node"
            operator = "In"
            values = ["true"]
      [runners.kubernetes.node_tolerations]
        "dagger-node" = ""
      [runners.kubernetes.pod_security_context]
        run_as_non_root = false
        run_as_user = 0
        [[runners.kubernetes.volumes.host_path]]
          name = "dagger"
          mount_path = "/run/dagger"
          host_path = "/run/dagger"
runner.yml
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dagger-runner
  namespace: dagger
spec:
  config: dagger-custom-config-toml
  gitlabUrl: YOUR-GITLAB-URL
  tags: dagger
  token: YOUR-GITLAB-RUNNER-TOKEN-REFERENCE
  runUntagged: false

Dagger Cloud Engines​

By default the CLI starts a Dagger Engine inside the GitLab runner. For a faster, more reliable experience, offload execution to a managed Dagger Engine provided by Dagger Cloud by adding --cloud to the command:

dagger check --cloud

Cloud Engines provide a large persistent cache shared across runs and far more compute than a GitLab runner, so checks are typically much faster — and you don't provision or maintain any infrastructure. This requires the DAGGER_CLOUD_TOKEN variable configured above.

Resources​

If you have any questions about additional ways to use GitLab with Dagger, join our Discord and ask your questions in our GitLab channel.

About GitLab​

GitLab is a popular Web-based platform used for version control and collaboration. It allows developers to store and manage their code in repositories, track changes over time, and collaborate with other developers on projects.