CircleCI

Dagger provides a programmable container engine that allows you to replace your YAML workflows in CircleCI with Dagger Functions written in a regular programming language. This allows you to execute your pipeline the same locally and in CI, with the additional benefit of intelligent caching.

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 executes one (or more) Dagger CLI commands, such as dagger call ....
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 calls the specified Dagger Function and sends telemetry to Dagger Cloud if the DAGGER_CLOUD_TOKEN environment variable is set.
7. The pipeline completes with success or failure. 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
• Docker, if using a CircleCI execution environment other than docker

Examples

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

The following example demonstrates how to call a Dagger Function in a CircleCI workflow.

.circleci/config.yml

version: 2.1
jobs:
  hello:
    docker:
      - image: cimg/base:2024.09
    steps:
      - 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: Call Dagger Function
          command: dagger -m github.com/shykes/daggerverse/hello@v0.1.2 call hello --greeting="bonjour" --name="monde"
      # for ephemeral runners only: override the default docker stop timeout and
      # give the Dagger Engine more time to push cache data to Dagger Cloud
      - run:
          name: Stop Dagger Engine
          command: docker stop -t 300 $(docker ps --filter name="dagger-engine-*" -q)
          when: always
workflows:
  dagger:
    jobs:
      - hello

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

The following is a more complex example demonstrating how to create a CircleCI workflow that checks out source code, calls a Dagger Function to test the project, and then calls another Dagger Function to build and publish a container image of the project. This example uses a simple Go application and assumes that you have already forked it in the repository connected to the CircleCI project.

.circleci/config.yml

version: 2.1
jobs:
  test:
    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: Test
          command: dagger -m github.com/kpenfound/dagger-modules/golang@v0.2.0 call test --source=.
      # for ephemeral runners only: override the default docker stop timeout and
      # give the Dagger Engine more time to push cache data to Dagger Cloud
      - run:
          name: Stop Dagger Engine
          command: docker stop -t 300 $(docker ps --filter name="dagger-engine-*" -q)
          when: always
  build:
    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: Build
          command: dagger -m github.com/kpenfound/dagger-modules/golang@v0.2.0 call build-container --source=https://github.com/golang/example#master:hello --args=. publish --address=ttl.sh/my-app-$RANDOM
      # for ephemeral runners only: override the default docker stop timeout and
      # give the Dagger Engine more time to push cache data to Dagger Cloud
      - run:
          name: Stop Dagger Engine
          command: docker stop -t 300 $(docker ps --filter name="dagger-engine-*" -q)
          when: always
workflows:
  dagger:
    jobs:
      - test
      - build:
          requires:
            - test

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

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.