Skip to main content

CircleCI

CircleCI can run dagger check in any workflow, so the same checks you run locally run on every push — without rewriting your pipeline.

tip

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

How it works​

When running a CI pipeline with Dagger using CircleCI, the general workflow looks like this:

  1. CircleCI receives a trigger based on a repository event.
  2. CircleCI begins processing the jobs and steps in the .circleci/config.yml workflow file.
  3. CircleCI downloads the Dagger CLI.
  4. CircleCI 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 CircleCI runner.
  6. The Dagger CLI 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 CircleCI as usual.
note

In a Dagger context, you won't have access to CircleCI's test splitting functionality. You will need to implement your own test distribution logic or run all tests in a single execution.

Prerequisites​

  • A CircleCI project
  • A GitHub, Bitbucket or GitLab repository connected to the CircleCI project
  • A repository with a Dagger workspace (.dagger/config.toml) — see Workspace Setup.
  • Docker, if using a CircleCI execution environment other than docker

Example​

The example below uses the docker executor, which comes with a Docker execution environment preconfigured. If using a different executor, such as machine, you must install Docker in the execution environment before proceeding.

The following example runs all of your workspace's checks with dagger check:

.circleci/config.yml
version: 2.1
jobs:
  check:
    docker:
      - image: cimg/base:2024.09
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Install Dagger CLI
          command: curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh
      - run:
          name: Run Dagger checks
          command: dagger check
workflows:
  dagger:
    jobs:
      - check

# assumes the Dagger Cloud token is
# in a project environment variable named DAGGER_CLOUD_TOKEN

dagger check runs every check and exits non-zero if any fails. You can scope it to a subset — for example dagger check go:* to run a single module's checks.

Dagger Cloud Engines​

By default the Dagger CLI starts a Dagger Engine inside the CircleCI 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 CircleCI runner, so checks are typically much faster — and you don't provision or maintain any infrastructure. This requires the DAGGER_CLOUD_TOKEN environment variable to be set in your CircleCI project.

Resources​

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

About CircleCI​

CircleCI is a popular CI/CD platform to test, build and deploy software applications.