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:
- CircleCI receives a trigger based on a repository event.
- CircleCI begins processing the jobs and steps in the
.circleci/config.yml
workflow file. - CircleCI downloads the Dagger CLI.
- CircleCI executes one (or more) Dagger CLI commands, such as
dagger call ...
. - The Dagger CLI attempts to find an existing Dagger Engine or spins up a new one inside the CircleCI runner.
- The Dagger CLI calls the specified Dagger Function and sends telemetry to Dagger Cloud if the
DAGGER_CLOUD_TOKEN
environment variable is set. - The pipeline completes with success or failure. Logs appear in CircleCI as usual.
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.
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.
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.