Mage in CI: Run Go Build Targets in Pipelines

In CI you install mage (or run it via go run) and call mage <Target> as pipeline steps.

Because magefiles are Go, Mage fits naturally into Go projects in CI. You can install the mage binary, compile a standalone runner, or invoke it with go run and no install.

What it does

A pipeline gets mage onto the runner, then runs targets: mage build, mage test. You can install the binary (go install github.com/magefile/mage), use the zero-install form go run github.com/magefile/mage <target>, or precompile a portable binary with mage -compile so the runner does not need the Go toolchain at run time. Each target exits non-zero on error, failing the step.

Common usage

# GitHub Actions, zero-install via go run
- uses: actions/setup-go@v5
  with:
    go-version: '1.22'
- run: go run github.com/magefile/mage -l
- run: go run github.com/magefile/mage test

# or install the binary first
go install github.com/magefile/mage@latest
mage build

# precompile a standalone runner (no Go needed at run time)
mage -compile ./magebin
./magebin test

Syntax

In CI

In a Go project, go run github.com/magefile/mage avoids a separate install step entirely. For runners without Go, ship a mage -compile binary so the build does not need the toolchain. Run mage -l early to record the available targets in the log.

Common errors in CI

"mage: command not found" means the binary was not installed and you did not use the go run form. "No .go files marked with the mage build tag" means the magefile is missing its //go:build mage tag or you ran from the wrong directory. "Unknown target" means the target is unexported or misspelled. With go run, a stale module cache can pull an unexpected mage version; pin with @<version>.

Related guides