Chainguard Checks on

Chainguard Checks overview

Thu, 08 Oct 2026 00:00:00 +0000

Chainguard Checks runs your repository’s CI on Chainguard’s infrastructure instead of on GitHub Actions runners. You define your checks, such as linting and tests, in a .chainguard/ci.yaml file in your repository. On every pull request, Chainguard Checks runs each check in its own microVM, built on Chainguard OS, and reports the results on the pull request as GitHub checks.

CI runners usually hold long-lived secrets and can reach the whole internet while they run untrusted code, such as a pull request’s changes or a compromised dependency. In Chainguard Checks, each check runs in a fresh VM that has no long-lived credentials, and no network access unless the check lists the hosts it needs.

Get started with Chainguard Checks

Thu, 08 Oct 2026 00:00:00 +0000

This guide walks you through signing up for Chainguard Checks, adding checks to one of your GitHub repositories, and seeing them run on a pull request. It uses a Go repository as the example and takes about 15 minutes.

Note: Chainguard Checks is in beta. Available to organizations that turn it on with chainctl develop init, which comes with a free monthly compute allowance, or that arrange access with their Chainguard account team.

Set up Chainguard Checks and Chainguard Workspaces

Tue, 13 Oct 2026 00:00:00 +0000

Chainguard Checks runs your repository’s CI on every GitHub pull request, with each check in its own microVM. Chainguard Workspaces runs your development work, and the coding agents that do it, in a remote microVM session that holds none of your long-lived credentials. You can use either product on its own, but they’re built to work together, and you set them up together: one command, chainctl develop init, turns on both. This page explains what the products share, then walks you through signing up and giving teammates access.

Chainguard Checks configuration reference

Thu, 08 Oct 2026 00:00:00 +0000

You define your checks in YAML configuration files in your repository’s .chainguard/ directory. This page describes the file format: where the files go, the packages and commands each check gets, and the options that control when and how checks run. For variations, inputs and outputs, services, and caches, refer to Variations, inputs, services, and caches.

The same files also set up Chainguard Workspaces sessions, and run-ci in a session runs the checks they define.

Variations, inputs, services, and caches in Chainguard Checks

Mon, 12 Oct 2026 00:00:00 +0000

Most checks need only the keys that the Chainguard Checks configuration reference describes. This page describes the keys for checks that need more: running a check once for each of several variations, passing files between checks, starting services such as a database, running as an unprivileged account, and reusing build output from earlier runs.

Run a check once per variation

The foreach key runs a check once for each entry in a list, each in its own VM. All of a check’s variations report as one GitHub check. For example, this check runs three variations, two at a time:

Workload identities and trust in Chainguard Checks

Mon, 12 Oct 2026 00:00:00 +0000

A check that must authenticate to Google Cloud or to Chainguard, such as to read a Cloud Storage bucket or to pull private images from cgr.dev, can use a workload identity: short-lived credentials that Chainguard Checks gives the check while it runs. This page explains how workload identities work, how to declare and set one up, how to limit which pull requests get one, and how to revoke access.

How workload identities work

A check’s VM holds no long-lived credentials. When a check uses a workload identity, Chainguard Checks issues the check an OpenID Connect (OIDC) token that lasts five minutes, renews the token while the check runs, and keeps the real credentials outside the VM:

Use Chainguard Checks on GitHub

Thu, 08 Oct 2026 00:00:00 +0000

Chainguard Checks runs on your GitHub repositories through the Chainguard App and reports its results as GitHub checks. This page explains when Chainguard Checks runs, how its results appear on GitHub, and how to use them to protect your branches.

When Checks runs

Chainguard Checks runs on a repository when the Chainguard App is installed on the repository, its GitHub account is linked to a Chainguard organization with access to Chainguard Checks, and the repository has a .chainguard/ci.yaml file or a .chainguard/ci/ directory. For a pull request, Chainguard Checks looks for the configuration on the pull request’s branch and on its base branch.

Run checks before you push with Chainguard Workspaces

Thu, 08 Oct 2026 00:00:00 +0000

Waiting for a pull request’s checks to find a mistake is slow, especially for a coding agent that has to push, wait, and read the results before it can try again. With Chainguard Workspaces, you can run your repository’s checks against your working tree, uncommitted changes included, before you push. This page explains how, and how to find mistakes in your configuration without running anything. To run checks on a pushed commit without a pull request, or to read results and your checks’ history from your terminal, refer to Inspect and run checks with chainctl.

Inspect and run checks with chainctl

Mon, 12 Oct 2026 00:00:00 +0000

The chainctl checks commands read your checks’ results from your terminal, so you or a coding agent can find out why a check failed without opening GitHub. This page explains how to inspect a pull request’s runs, how to run checks on a pushed commit without opening a pull request, and how to find the checks that take the most time or fail most often. For every command and flag, refer to the chainctl checks command reference.

Migrate from GitHub Actions to Chainguard Checks

Thu, 08 Oct 2026 00:00:00 +0000

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.

chainctl checks command reference

Mon, 12 Oct 2026 00:00:00 +0000

The chainctl checks commands read your pull requests’ results from your terminal, start and rerun checks, summarize your checks’ history, and validate your configuration. This page lists each command’s arguments, flags, exit codes, and JSON output. For examples of the commands in use, refer to Inspect and run checks with chainctl.

During the beta, the chainctl checks and chainctl develop commands don’t appear in chainctl --help or in the chainctl reference. You can still run them, and --help on either one shows its full help.

Troubleshoot Chainguard Checks

Thu, 08 Oct 2026 00:00:00 +0000

This page describes common problems with Chainguard Checks and how to fix them. If your problem isn’t listed here, ask in the #checks-questions channel in the Chainguard community Slack.

A pull request gets no checks

If a pull request shows no Chainguard Checks (presubmit) check at all, Chainguard Checks didn’t start a run for it. Confirm the following: