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.
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
dockergroup (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:

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:

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:

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:

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_VERSIONmatches the CLI that created the module- Step
env:exportsGITHUB_TOKENasREGISTRY_PASSWORD packages: writelets the job push to GHCRneeds: testkeeps 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:

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.testitself: 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:
| Scenario | No cache volumes | With cache volumes |
|---|---|---|
| Cold engine (fresh runner) | 126.5 s / 131.4 s | 151.9 s / 129.5 s |
| Warm engine, no code change | 4.4 s / 4.5 s | 7.2 s / 4.7 s |
| Warm engine, edit to main.go | 34.2 s, 34.5 s / 35.6 s, 35.5 s | 9.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:

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:

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:

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:
| Input | Default | What it does |
|---|---|---|
version | latest | Dagger CLI release to install; pin it to engineVersion in dagger.json |
verb | call | CLI verb: check, call, run, download, up, functions, shell or query |
call | empty | Function and arguments for dagger call |
args | empty | Raw arguments for any verb |
shell / check | empty | Script or function for dagger shell and dagger check |
module | empty | Module 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 plain | Global CLI flags |
cloud-token | empty | Dagger Cloud token for traces |
enable-github-summary | false | Write a job summary to the Actions run page |
summary-path | empty | Write the summary to this file, even with enable-github-summary off |
commit | empty | Install a development build by commit |
engine-stop | none | Deprecated, 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_VERSIONin the same pull request asdagger.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.