Migrate from GitHub Actions to Chainguard Checks

If your repository runs its pull request checks with GitHub Actions, you can move them to Chainguard Checks one workflow at a time. Chainguard Checks and GitHub Actions can run on the same pull requests, so you can compare their results before you remove a workflow.

You can convert workflows by hand, or start from a draft that the chainctl checks migrate command writes for you.

If you’d rather keep your workflows on GitHub Actions, Chainguard Actions replaces the actions they use with hardened equivalents, and Guardener’s Hardened Actions feature can migrate them for you.

Draft a configuration with chainctl

The chainctl checks migrate --dry command drafts a configuration from your GitHub Actions workflows without running anything. Run it from the root of a local clone of your repository whose origin remote is on github.com:

chainctl checks migrate --dry

The command reads each workflow that runs on pull_request and prints a draft .chainguard/ci/migrated.yaml file, followed by a list of what it carried over, flagged, and ignored. To write the draft to its file, run the following commands:

mkdir -p .chainguard/ci
chainctl checks migrate --dry -o json | jq -r .document > .chainguard/ci/migrated.yaml

The draft has one check for each job it can carry over, and a separate check for each combination of a static matrix of up to 8 combinations. A job whose matrix uses include or an expression, or has more than 8 combinations, isn’t carried over. The list after the draft flags it, so convert it by hand. The draft’s checks appear on GitHub as presubmit / migrated / <check>.

The draft uses the directory layout, and a repository can’t use both layouts. If your repository already has a .chainguard/ci.yaml file, move its checks into a file in .chainguard/ci/, and its environment to .chainguard/ci/env/default.yaml, before you add the draft.

Review the draft before you commit it:

• Add the packages each check needs. The draft lists packages for setup actions, such as actions/setup-go, but not for tools that the GitHub Actions runner image includes, such as git and make.
• Add the hosts each check needs under network.egress. The draft gives checks no network access. To find the hosts, refer to Find the hosts a check needs.
• For each check that needs x86-64, set resources to a class that pins it, such as the built-in medium-amd64. The draft ignores runs-on, so its checks usually run on arm64.
• Read each # migrator: comment. Each one marks something the draft couldn’t carry over, such as a step that uses a third-party action, a step with a ${{ }} expression, a service container, or a paths filter. Convert each one by hand.

Then run chainctl checks validate to check the result. The rest of this page explains how to convert what the draft leaves out, including workflows that run on other events, such as push.

How the models differ

A GitHub Actions job starts on a general-purpose runner image, checks out your code, and installs its tools with setup actions before running its commands. In Chainguard Checks, a check starts in a minimal VM with your code already in /work, installs the packages you list, and runs its commands. The following table summarizes the differences:

Key mapping

The following table maps common GitHub Actions keys and actions to their Chainguard Checks equivalents:

Refer to the configuration reference for each Chainguard Checks key.

Example

The following GitHub Actions workflow runs Go tests on pull requests that change Go files:

name: test
on:
  pull_request:
    paths: ["**/*.go", "go.mod", "go.sum"]
jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.24"
      - run: go test ./...
        env:
          CGO_ENABLED: "0"

The equivalent .chainguard/ci.yaml file installs Go 1.24 as a package instead of using actions/setup-go and drops actions/checkout:

version: 1
environment:
  packages: [go-1.24]
checks:
  test:
    cmd: go test ./...
    vars:
      CGO_ENABLED: "0"
    timeout: 15m
    when:
      changed: ["**/*.go", "go.mod", "go.sum"]
    network:
      egress: [proxy.golang.org, sum.golang.org]

The network key lets the check download modules. The workflow doesn’t list these hosts, because a GitHub Actions job can reach any host. To find the hosts a check needs, refer to Find the hosts a check needs.

By default, actions/setup-go caches downloaded modules and build output between runs. This file uses no cache, so each run downloads its modules and builds from scratch. To reuse Go build output between runs, add the gobuild cache, as described in Caches. During the beta, Chainguard Checks doesn’t cache modules, so keep the network hosts. With the cache, go test still runs every test instead of reusing earlier results.

Find the hosts a check needs

The run page that a check’s Details link opens lists each host the check tried to reach, and suggests an egress list built from the hosts it connected to. The suggestion includes only connections that the check’s egress allowed, so to see every host a check uses, let it reach any host for one run:

1. In a pull request whose code you trust, set the check’s network.egress to ["*"]. With *, the check’s commands can reach any public host.
2. When the check finishes, open its Network activity on the run page, as described in A check can’t reach a host.
3. Review the hosts listed after Suggested allowlist (review before applying), replace * with them, and push the change.

The suggestion covers only that run. It leaves out connections to an IP address that the check didn’t look up by name, and hosts that the check reaches only on other paths, such as retries, fallback mirrors, or code that the run didn’t exercise.

To open the run page, you need a role in your Chainguard organization, as described in The Details link or a chainctl checks command says you don’t have access. Without one, list the hosts you expect, run the check, and look in its log for connection errors.

Switch over

To move a workflow to Chainguard Checks without a gap in coverage, follow these steps:

1. In a pull request, add the equivalent checks to .chainguard/ci.yaml, or add the .chainguard/ci/migrated.yaml file that you drafted, and keep the GitHub Actions workflow.
2. Compare the results of both on that pull request and the ones after it.
3. When the results match, add Chainguard Checks (presubmit) as a required status check, as described in Require checks before merging.
4. Remove the GitHub Actions workflow, and remove its jobs from your required status checks.