CI that keeps up
migrationby Kyle Penfound

How do I migrate from GitHub Actions to Dagger?

You do not have to rewrite your workflows as Dagger code. Dagger’s official modules find the tests and linters in your repository and run them as checks, on your machine and in Dagger Cloud. Move in four steps: install the modules, run the checks locally, turn on Cloud Checks, then turn off each workflow that the checks replace.

Do I have to rewrite my pipelines?

No, not for the work that an official module does. A Dagger module adds work to your project, such as tests or lint, and the Dagger team maintains official modules for common tools. Each official module finds the files of its tool in your repository. For example, the Go module finds each go.mod, and makes each Go package and test a check.

A check is a command that verifies your project and passes or fails, such as a test run or a linter. Today the official modules cover Go, golangci-lint, Staticcheck, Deno, Jest, Vitest, Playwright, ESLint, Prettier, Biome, pytest, ShellCheck, PSScriptAnalyzer, and Helm. The module reference lists them.

You write code only for work that no official module does, such as a deploy step. You do not copy the structure of your workflow YAML.

Install the official modules

Install the Dagger CLI. Then, from the root of your repository, initialize the workspace:

dagger init

The workspace is the Dagger configuration of your repository, in a file named dagger.toml (Quickstart). In a terminal, dagger init asks which modules to install. Without a terminal, it prints the next commands:

Workspace configuration initialized at ./dagger.toml

To continue setup, run these commands in order:

#!/bin/sh

# 1. Find and install suitable modules
dagger module recommend

# 2. Enable cloud checks
dagger cloud checks on

Install the modules that Dagger recommends for your repository:

dagger module recommend

In a terminal, select the modules to install. To install all of them with no prompt, add -y. In a Go repository, the command installs the Go module and adds it to dagger.toml:

[modules.go]
source = "dagger.io/go"

The command also writes dagger.lock. This file pins the versions of the modules and images that the workspace uses. Commit it with dagger.toml.

If Dagger recommends no module for one of your tools, search for one by the name of the tool, such as dagger module search eslint.

Run the checks on your machine

List the checks that the modules found:

dagger check -l
MODULE  GO-PACKAGE  GO-TEST  CHECK  DESCRIPTION
go      *                    stale  staleness check: run go generate in this package
go      *           *        test   Run this test.

A * stands for each item that the module found, such as each package or each test. Add --all to list one row per item. Run all the checks:

dagger check

The command exits with a non-zero code when a check fails (Checking your code). To run one test, select it by name:

dagger check --go-test=TestGet

Compare the list of checks with the jobs in your workflows. Each job that a check replaces is a job that you can turn off later.

Move custom steps into your own module

Write a Dagger module for each step that no official module covers, such as a release or a deploy. You can write modules in Dang, Dagger’s own language, or in Go, Python, TypeScript, Java, PHP, or Elixir (SDKs). A module can find out if it runs on the main branch. Use that to deploy to production from main, and to a preview environment from a pull request (branch filtering).

Keep your secrets where they are. Dagger reads a secret from its provider when a function needs it. Providers include HashiCorp Vault, 1Password, AWS Secrets Manager, and environment variables (Secrets). A function gives a secret to a container as an environment variable or as a mounted file (Container API). Dagger redacts secret values from logs, never writes them to container layers, and leaves them out of cache keys (Secrets).

Turn on Cloud Checks

Cloud Checks run your checks on Dagger Cloud after each push and pull request, with no workflow file (Set up Cloud Checks). They use the same checks as dagger check on your machine. The repository must be on GitHub, and its origin remote must point to it.

From the root of your repository, run:

dagger cloud checks on

In a terminal, the command helps you sign in to Dagger Cloud and connect your GitHub organization. Then commit dagger.toml and dagger.lock, and push. The push starts your checks. Each check shows on the pull request as a GitHub check, with a link to its trace (GitHub Checks integration).

Move one workflow at a time

Keep GitHub Actions on while you set up Dagger. For each workflow, compare its results with the Dagger checks that replace it. Then do these steps:

  1. Make the Dagger checks required status checks in your branch protection rules.
  2. Remove the workflow’s checks from the required list.
  3. Disable the workflow.

During the move, a workflow can also run dagger check as one of its steps (Checking your code in CI).

What stays the same

GitHub stays your home for code, pull requests, and review. Your tests stay as they are: official modules run them with no change to the test code (test-native CI). Your secret managers stay the source of your secrets.

Bottom line: You migrate from GitHub Actions to Dagger without a rewrite. Install the official modules that dagger module recommend finds, and run the same checks locally. Then turn on Cloud Checks and retire each workflow when its Dagger checks pass.