Automation

Use Dagger with GitHub Actions: CI/CD Pipeline Guide

Dagger runs your pipeline as code inside containers, and GitHub Actions only has to start it. The official dagger/dagger-for-github action installs the CLI, starts the engine and runs one dagger call, so the exact command that passes on your laptop is the one that runs on the runner. When a build breaks, you reproduce it locally in seconds instead of pushing commits to guess at YAML.

Original content from computingforgeeks.com - post 165363

I rebuilt this guide from scratch on an Ubuntu 24.04 box in November 2026 with Dagger 0.21.11 and dagger-for-github v8.4.1. Every command and output below comes from that run. The old version was a thin walkthrough that Search Console filed under Crawled - currently not indexed, so this one leans on measured runs instead. We will write a small Go service, wrap its test, build and publish steps in a Python Dagger module, wire it into a workflow, and then measure what cache volumes buy you on cold and warm engines.

One thing changed since the first version of this article. The install page on docs.dagger.io now hands out the 1.0 beta, which drops dagger init --sdk entirely. We pin the stable 0.21 line on purpose here, and section 10 shows what happens if you do not.

What You Need

Dagger needs a container runtime on the machine that runs it, both locally and on the CI runner. Hosted ubuntu-latest runners already ship Docker, so the list is mostly about your workstation:

  • A Linux host with Docker Engine running and your user in the docker group (our Docker and Docker Compose install on Ubuntu covers both)
  • 4 GB of RAM or more and about 10 GB of free disk for the engine image and its cache
  • A GitHub repository you can push to, with Actions enabled
  • Git and curl

Our lab was a 4 vCPU, 16 GB Ubuntu 24.04.5 VM with Docker 29.1.3 from the Ubuntu archive. Treat that as a comfortable floor for local work, not a sizing target: a busy self-hosted runner that keeps the engine cache around for many repositories will want more disk long before it wants more CPU. Rocky and AlmaLinux hosts need a few extra kernel modules first, which our Dagger on Rocky Linux and AlmaLinux walkthrough handles.

1. Install the Dagger CLI and Pin the Version

Install the CLI into ~/.local/bin with the official script and pin the version in a variable. We pin because the module we create records the engine version it was made with, and the CI workflow has to run the same release. Pinning also keeps you off the 1.0 beta until you decide to move:

export DAGGER_VERSION="0.21.11" # pin: 1.0 betas drop init --sdk #https://github.com/dagger/dagger/releases
curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh

Our run downloaded the tarball and its checksum file, verified it, and printed shell completion instructions. The lines that matter are at the start and the end:

sh debug downloading files into /tmp/tmp.6vL44IkoGk
sh debug http_download https://dl.dagger.io/dagger/releases/0.21.11/dagger_v0.21.11_linux_amd64.tar.gz
sh debug http_download https://dl.dagger.io/dagger/releases/0.21.11/checksums.txt
...
sh info installed /home/kibet/.local/bin/dagger

Ubuntu adds ~/.local/bin to PATH at login only when the directory already exists, so if dagger is not found, log out and back in or run export PATH="$HOME/.local/bin:$PATH" for the current shell. Then confirm the version and the engine image it will use:

dagger version

The engine image tag always matches the CLI version, which is why mixing versions on one host causes trouble later:

dagger v0.21.11 (image://registry.dagger.io/engine:v0.21.11) linux/amd64

If you already have Dagger from our Dagger install guide for Ubuntu, check that this line reports the same version you plan to put in the workflow.

2. Create a Small Go Service to Build

We need something real to test and ship, so the sample is a tiny HTTP service with one dependency and one unit test. A dependency matters here because it is what makes the module cache worth measuring later. Create the project and a Git repository for it:

mkdir ~/my-app && cd ~/my-app
git init -b main

Open the main program file.

vim main.go

Paste the service. It answers on port 8080 and greets whatever name is in the path:

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/go-chi/chi/v5"
)

func Greeting(name string) string {
	if name == "" {
		name = "homelab"
	}
	return fmt.Sprintf("Hello, %s!", name)
}

func main() {
	r := chi.NewRouter()
	r.Get("/", func(w http.ResponseWriter, _ *http.Request) {
		fmt.Fprintln(w, Greeting(""))
	})
	r.Get("/{name}", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintln(w, Greeting(chi.URLParam(req, "name")))
	})
	log.Println("listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", r))
}

Next comes the test file, which the test function will run.

vim main_test.go

Both the default greeting and a named one get checked:

package main

import "testing"

func TestGreeting(t *testing.T) {
	if got := Greeting(""); got != "Hello, homelab!" {
		t.Fatalf("unexpected greeting: %q", got)
	}
	if got := Greeting("kibet"); got != "Hello, kibet!" {
		t.Fatalf("unexpected greeting: %q", got)
	}
}

Now create the module file.

vim go.mod

Declare the module path and the chi router version.

module example.com/my-app

go 1.25

require github.com/go-chi/chi/v5 v5.5.0

You do not need Go installed on the host to generate go.sum. A throwaway container does it, and running it as your own UID keeps the file owned by you instead of root (we got a root-owned go.sum on the first try without -u):

docker run --rm -u "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD":/src -w /src golang:1.25-alpine go mod tidy

Chi downloads once and the checksums land in go.sum:

go: downloading github.com/go-chi/chi/v5 v5.5.0

The project now has four files and no pipeline yet, which is exactly the starting point most real repositories are in when they adopt Dagger.

3. Initialize a Python Dagger Module

dagger init turns the repository into a Dagger module: it writes dagger.json and generates the SDK code under .dagger/. We use the Python SDK because most teams can read it without learning a new language, but the Go and TypeScript SDKs produce the same module shape. Run it from the project root:

dagger init --sdk=python --name=my-app

The first run took 1 minute 17 seconds on our VM because it pulled the engine image and built the Python SDK runtime. It also drops an Apache 2.0 LICENSE into the repo if none exists, so delete or replace it if your project uses another license:

dagger init creating a Python module with engineVersion v0.21.11 in dagger.json on Ubuntu 24.04

Look at engineVersion in that dagger.json. It is a floor, not a label: any CLI older than the recorded version refuses to load the module. That is the first error in section 10, and it is the reason the workflow pins the same version we installed.

Have a quick look at the generated files so you know what to commit. The SDK directory holds hundreds of files, so we skip its contents:

find .dagger -maxdepth 3 -not -path ".dagger/sdk/*"

The module source sits under src/my_app, next to the Python project files:

.dagger
.dagger/src
.dagger/src/my_app
.dagger/src/my_app/__init__.py
.dagger/src/my_app/main.py
.dagger/.gitattributes
.dagger/.gitignore
.dagger/sdk
.dagger/pyproject.toml
.dagger/uv.lock

Commit everything except .dagger/sdk, which the generated .dagger/.gitignore already excludes along with .venv and __pycache__. The engine regenerates the SDK on every runner, so checking it in only adds noise to your diffs.

4. Write the Pipeline Functions

Each @function in main.py becomes a command you can call from the CLI, from GitHub Actions or from another module. We define three: test, build and publish, all sharing one Go toolchain container. Replace the generated example:

vim .dagger/src/my_app/main.py

We ran this exact file for every capture in this article.

import dagger
from dagger import dag, function, object_type

GO_IMAGE = "golang:1.25-alpine"

@object_type
class MyApp:
    def go_env(self, source: dagger.Directory) -> dagger.Container:
        """Go toolchain with module and build caches mounted"""
        return (
            dag.container()
            .from_(GO_IMAGE)
            .with_mounted_cache("/go/pkg/mod", dag.cache_volume("go-mod"))
            .with_mounted_cache("/root/.cache/go-build", dag.cache_volume("go-build"))
            .with_env_variable("CGO_ENABLED", "0")
            .with_mounted_directory("/src", source)
            .with_workdir("/src")
        )

    @function
    async def test(self, source: dagger.Directory) -> str:
        """Run go vet and go test"""
        return await (
            self.go_env(source)
            .with_exec(["go", "vet", "./..."])
            .with_exec(["go", "test", "-v", "./..."])
            .stdout()
        )

    @function
    def build(self, source: dagger.Directory) -> dagger.File:
        """Compile a static Linux binary"""
        return (
            self.go_env(source)
            .with_exec(["go", "build", "-o", "/out/app", "."])
            .file("/out/app")
        )

    @function
    async def publish(
        self,
        source: dagger.Directory,
        registry: str,
        image: str,
        username: str,
        password: dagger.Secret,
        tag: str = "latest",
    ) -> str:
        """Build the runtime image and push it to a registry"""
        return await (
            dag.container()
            .from_("alpine:3.22")
            .with_file("/usr/local/bin/app", self.build(source))
            .with_entrypoint(["/usr/local/bin/app"])
            .with_exposed_port(8080)
            .with_registry_auth(registry, username, password)
            .publish(f"{registry}/{image}:{tag}")
        )

Three choices in this file carry most of the weight. The two with_mounted_cache lines keep the Go module downloads and compiled packages in named cache volumes, so a code change only recompiles what changed. go_env has no @function decorator, which keeps it a private helper instead of a CLI command. And password is typed dagger.Secret rather than str, which means the value never lands in logs, traces or the layer cache.

Why not just mount the source and run go test? We tried that first. It works, but every edit to main.go paid for a full module download and compile, which you can see in the timing table in section 9.

5. Run the Pipeline Locally

Before touching GitHub, prove the pipeline on your machine. dagger functions lists what the module exposes, and dagger call test runs the test function with the current directory as its source:

dagger functions
dagger call test --source=.

Docstrings from main.py show up as descriptions, and the test function returns the go test -v output as its result:

dagger functions listing build, publish and test, then dagger call test passing go test

Because build returns a File, you can chain export onto it and pull the binary out of the engine onto the host. That is a quick way to check the build really produces something runnable:

dagger call build --source=. export --path=./app
file ./app
./app &
sleep 1
curl -s localhost:8080/kibet

The binary is statically linked thanks to CGO_ENABLED=0, which is what lets it run on a bare Alpine image in the next step:

dagger call build export writing a static Go binary that answers Hello, kibet! on port 8080

Stop the background process with kill %1 when you are done, and add app to your .gitignore so the exported binary never gets committed.

6. Publish an Image with a Secret

Secrets go into Dagger as URIs, not values. env://REGISTRY_PASSWORD tells the CLI to read the variable from its own environment and hand it to the engine as a secret, which is the same mechanism the workflow uses with GITHUB_TOKEN. We tested the push against ttl.sh, an anonymous registry whose images expire on their own, so any token value works:

export REGISTRY_PASSWORD=not-a-real-token
dagger call publish --source=. --registry=ttl.sh --image=homelab-ci-demo-7018 --username=kibet --password=env://REGISTRY_PASSWORD --tag=1h

Back comes the pushed reference with its digest, which you can feed to a deploy step or a signing tool:

dagger call publish pushing an image to ttl.sh with an env:// secret and printing the sha256 digest

Change the registry to ghcr.io and the password to a real token and nothing else in the function moves. Getting the secret syntax wrong is the most common way this step fails, and section 10 shows both error messages we hit.

7. Add the GitHub Actions Workflow

The workflow stays short because the logic lives in the module. One job runs test on every push and pull request, and a second job publishes to GitHub Container Registry only on pushes to main. Create the file:

mkdir -p .github/workflows
vim .github/workflows/ci.yml

Paste the workflow below.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  DAGGER_VERSION: "0.21.11"

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7

      - name: Run tests with Dagger
        uses: dagger/dagger-for-github@v8
        with:
          version: ${{ env.DAGGER_VERSION }}
          call: test --source=.

  publish:
    name: Build and push image
    runs-on: ubuntu-latest
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    timeout-minutes: 15
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v7

      - name: Publish to GHCR
        uses: dagger/dagger-for-github@v8
        env:
          REGISTRY_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
        with:
          version: ${{ env.DAGGER_VERSION }}
          call: >-
            publish
            --source=.
            --registry=ghcr.io
            --image=${{ github.repository }}
            --username=${{ github.actor }}
            --password=env://REGISTRY_PASSWORD
            --tag=${{ github.sha }}

A few lines deserve a closer read before you commit it, because each one fixes a failure we would otherwise hit on the first push:

  • DAGGER_VERSION matches the CLI that created the module
  • Step env: exports GITHUB_TOKEN as REGISTRY_PASSWORD
  • packages: write lets the job push to GHCR
  • needs: test keeps a failing build out of the registry

The action accepts the version with or without the leading v, and no personal access token is involved because GITHUB_TOKEN plus packages: write covers GHCR. One catch we know of but did not hit: GHCR rejects image names with uppercase letters, so if your owner or repo name has capitals, pass a lowercase --image instead of github.repository.

To be clear about what we tested: the workflow file was validated as YAML, and the step it runs was executed on the Ubuntu VM in the next section. We did not push it to a hosted runner for this refresh. If you are moving existing runners at the same time, our notes on what breaks when ubuntu-latest moves to Ubuntu 26.04 are worth reading first, because Dagger only isolates the steps inside the engine, not the runner around it.

8. What the Action Runs on the Runner

dagger-for-github v8 is a composite action, so you can read exactly what it does. When the CLI is missing, or reports a version other than the version input, it runs the same install.sh we used in section 1 into $RUNNER_TEMP/bin, then executes dagger --progress plain call with your call input appended. That means you can reproduce a CI run byte for byte on any Linux box. We removed the engine container and its cache to get a cold engine and ran that same command. One difference from a hosted runner remains: the engine image was still on our VM, so this run skipped the image pull that a fresh runner also pays.

dagger --progress plain call test --source=.

Plain progress prints one line per operation instead of the interactive tree, which is what you see in the Actions log. The trimmed log shows where a cold job spends its time:

dagger --progress plain log showing the engine container start, removal of the old engine and the cold test run

The whole run finished in 112 seconds. Reading the log top down, the time split like this:

  • Connect, including 1.1 seconds of engine start: 2.7 seconds
  • Python SDK type definitions: 1 minute 7 seconds
  • Loading the module object: 3.3 seconds
  • MyApp.test itself: 38.9 seconds

So the biggest single cost is not your build at all. loading type definitions is the Python SDK runtime being built inside the fresh engine, and a cold runner pays it on every job. Most of the test step went to pulling golang:1.25-alpine, downloading chi and compiling, which is exactly what the cache volumes target once the engine stays warm.

Notice the docker rm -fv dagger-engine-v0.20.3 line as well. The CLI found an engine from another release on the host and deleted it together with its volume. On a hosted runner nobody cares, but on a self-hosted runner shared by repositories pinned to different releases, every job wipes the cache the previous job built. We come back to that in section 10.

9. Cold vs Cached: Measured Times

Do cache volumes speed up CI? On a warm engine, a lot. On a cold one, not at all. We timed dagger call test with and without the two cache mounts, two rounds each, starting every round by deleting the engine container, its volume and its image:

ScenarioNo cache volumesWith cache volumes
Cold engine (fresh runner)126.5 s / 131.4 s151.9 s / 129.5 s
Warm engine, no code change4.4 s / 4.5 s7.2 s / 4.7 s
Warm engine, edit to main.go34.2 s, 34.5 s / 35.6 s, 35.5 s9.5 s, 9.5 s / 9.4 s, 9.5 s

The edit row is the one that matters day to day. Without cache volumes, changing one line of Go invalidates the layer that runs go test, and Go starts again from an empty module and build cache: about 35 seconds. With the volumes mounted, the same edit costs about 9.5 seconds, roughly a 3.7x cut. When nothing changed, both variants return in under 8 seconds because the Dagger layer cache skips the work entirely.

For ubuntu-latest, the cold row is the honest one. Cache volumes live inside the /var/lib/dagger volume of the engine, and a hosted runner is thrown away after each job, so every job starts cold at around two minutes whatever you mount. We did not log per phase in that round, so the 151.9 second outlier is most likely pull variance; the second round came in at 129.5. If you want the warm numbers in CI, the engine has to outlive the job, which means a self-hosted runner that keeps its engine container. Comparing that cost against plain Actions caching is a big part of our Dagger vs GitHub Actions comparison.

10. Errors We Hit and How to Fix Them

Every error below came up while building this lab. Most of them are version or secret mistakes that look confusing the first time and take one line to fix.

Error: “module requires dagger v0.21.11, but you have v0.20.3”

Here is the engine version mismatch. The module records engineVersion in dagger.json when you run dagger init, and an older CLI refuses to load it. We reproduced it by installing the previous release next to the current one and calling the same module:

Dagger v0.20.3 CLI failing with module requires dagger v0.21.11 error

In CI this happens when a developer upgrades Dagger locally and commits a dagger.json written by the newer CLI while the workflow still pins the old version. Fix it by raising DAGGER_VERSION in the workflow to match engineVersion, in the same commit, so the runner and the module always agree.

Error: “unknown flag: –sdk” on dagger init

If you follow the current install page on docs.dagger.io without a version, you get the 1.0 beta. Its dagger init sets up a workspace instead of a module and no longer takes --sdk:

Dagger v1.0.0-beta.27 rejecting dagger init with Error: unknown flag: --sdk

Reinstall with DAGGER_VERSION set as in section 1. If you do want the beta, module creation moved to dagger module init, and plain dagger init now creates a workspace. The beta CLI can still run a module created by the stable line: our 0.21 module passed its tests under the beta with a notice that read “No workspace config found, inferring from dagger.json. Run ‘dagger workspace migrate’ when ready.” The reverse fails, though. A project initialized by the beta made the stable CLI answer unknown command "test" for "dagger call", so do not let one teammate on the beta commit generated files for everyone else.

Error: “secret env var not found”

We got this message in two different ways. The first call below had env://REGISTRY_PASSWORD right but the variable was not exported in that shell. The second passed the password value itself instead of a URI:

Dagger secret env var not found error and missing URI scheme deprecation warning

Watch out for the second case. Without a scheme, Dagger treats the argument as the name of an environment variable and prints a deprecation warning, misspelling included, that echoes the full value you passed. In a CI log that is a leaked credential. Errors shorten the secret name to three characters, as in "REG...", but that warning does not shorten anything.

So always pass a URI scheme. env://, file:// and cmd:// cover most cases, and the CLI also has providers for 1Password (op://), Vault (vault://), AWS Secrets Manager and Parameter Store, libsecret and GCP Secret Manager. In GitHub Actions, set the variable in the env: block of the step, because repository secrets never reach the shell inside the action unless you map them there.

Cache gone after a job pinned another Dagger version

Nothing errors here; the build just goes slow again. The engine runs as a container named dagger-engine-v<version> with an anonymous volume for /var/lib/dagger, and when a CLI of a different version starts, it removes the other engine with docker rm -fv. The -v deletes the volume, and with it every cache volume and layer. On a self-hosted runner, two repositories pinned to different Dagger releases will keep wiping both caches. You can see what is running with:

docker ps -a --format '{{.Names}} {{.Status}}' --filter name=dagger-engine

Our VM showed a single engine after the swap, because the older one had already been removed:

dagger-engine-v0.21.11 Up 9 minutes

There is an escape hatch. The CLI reads DAGGER_LEAVE_OLD_ENGINE (the 1.0 beta docs describe it under User configuration, Old engines), and with it set to true the older CLI started its own engine and left the current one alone. We checked the containers again after that run.

dagger-engine-v0.20.3 Up 3 seconds
dagger-engine-v0.21.11 Up 16 minutes

The variable only protects other engines while it is set, so the next job that runs without it still removes them. On a self-hosted runner, set it for every job, at workflow level or in the runner’s own environment, not on a single step. Both caches survive, but you now run two privileged engines on one runner, each with its own memory and disk. Treat the variable as a stopgap during an upgrade. The cleaner policy is one Dagger version per self-hosted runner pool, with DAGGER_VERSION upgraded in every repository together.

dagger-for-github v8 Input Reference

These are the inputs defined in action.yml at v8.4.1, which is the release @v8 resolved to when we checked. Most workflows only need version and call:

InputDefaultWhat it does
versionlatestDagger CLI release to install; pin it to engineVersion in dagger.json
verbcallCLI verb: check, call, run, download, up, functions, shell or query
callemptyFunction and arguments for dagger call
argsemptyRaw arguments for any verb
shell / checkemptyScript or function for dagger shell and dagger check
moduleemptyModule to load, local path or Git URL; empty means the CLI finds it from workdir
workdir.Directory the CLI runs in, useful in monorepos
dagger-flags--progress plainGlobal CLI flags
cloud-tokenemptyDagger Cloud token for traces
enable-github-summaryfalseWrite a job summary to the Actions run page
summary-pathemptyWrite the summary to this file, even with enable-github-summary off
commitemptyInstall a development build by commit
engine-stopnoneDeprecated, now a no-op

Two outputs come back as well, output with the stdout of the command and traceURL with the Dagger Cloud trace link, so a later step can read the image digest that publish returns via steps.<id>.outputs.output. The full source is in the dagger-for-github repository, and the module API used above is documented on docs.dagger.io.

What I Would Change for Production

The workflow above is already safer than most starter templates, but after timing it I would make a few more decisions before rolling it out across a team:

  • Pin the action to a full commit SHA instead of @v8
  • Bump DAGGER_VERSION in the same pull request as dagger.json
  • Use a self-hosted runner with a persistent engine
  • Stay on the stable line until the 1.0 workspace migration is planned

A SHA pin protects you from a moved tag, and Dependabot can still bump it. The persistent engine is the only way the 9.5 second rebuild from section 9 ever shows up in CI, since hosted runners always start cold.

For the timeouts, 15 minutes is generous for this service. Our cold runs took between 112 and 152 seconds, so a job that hits the limit is stuck pulling an image or waiting on a registry, and you want it killed rather than burning runner minutes. If your current pipelines are written for another tool, the patterns in our Earthly to Dagger migration guide map well onto this module layout, and a forge you host yourself can call the same functions, as our Woodpecker CI with Forgejo setup shows for a non-GitHub stack.

Keep reading

OpenCode CLI Cheat Sheet: Commands, Sessions and Fixes (PDF) AI OpenCode CLI Cheat Sheet: Commands, Sessions and Fixes (PDF) What Is DeepSeek Harness? Install dsh and Run Your First Agent AI What Is DeepSeek Harness? Install dsh and Run Your First Agent Best UI Applications for Managing Docker Containers Containers Best UI Applications for Managing Docker Containers OpenCloud vs ownCloud vs Nextcloud: Tested on Identical VMs Cloud OpenCloud vs ownCloud vs Nextcloud: Tested on Identical VMs Kiri Container Runtime on Linux: Install and Benchmark vs Docker Containers Kiri Container Runtime on Linux: Install and Benchmark vs Docker Kubernetes Node Management in Rancher Containers Kubernetes Node Management in Rancher

Leave a Comment

Press ESC to close