Chainguard Checks on

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. For how the two products isolate your code, refer to How Chainguard Checks and Chainguard Workspaces isolate your code.

Chainguard Checks overview

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

Chainguard Checks runs your pull requests’ checks, such as linting and tests, on Chainguard’s infrastructure, and reports the results on the pull request’s Checks tab on GitHub, beside any other checks the repository runs. You define the checks in a .chainguard/ci.yaml file in your repository, in Chainguard Checks’ own format. Chainguard Checks doesn’t run GitHub Actions workflows, so moving a workflow’s jobs to it means writing that file, as described in Migrate from GitHub Actions.

Tutorial: Fix a failing check with Claude Code in a Chainguard Workspaces session

Thu, 12 Nov 2026 15:30:50 +0000

Chainguard Checks and Chainguard Workspaces are built to work together: a coding agent changes your code in a Workspaces session, run-ci runs your checks against the change before you push, and Chainguard Checks runs the same checks on the pull request. When a check fails, the agent reads why from the session and fixes it.

In this tutorial, you walk that loop once with a small Go project. You open a session, let Claude Code add a function, check the change with run-ci, and open a pull request whose checks pass. Then you break a test on purpose, push without running run-ci, read the failure from the session with chainctl checks failures, and let Claude Code fix it.

How Chainguard Checks and Chainguard Workspaces isolate your code

Thu, 15 Oct 2026 12:09:53 +0000

Chainguard Checks runs your pull request checks, and Chainguard Workspaces runs your development sessions and coding agents, in microVMs that hold none of your long-lived credentials. This page collects the security model of both products in one place, for security reviewers who need to decide whether to allow them and for coding agents that need the rules. It describes how each product isolates code, where credentials come from, what code can reach on the network, who decides what a pull request gets, and how runs and sessions move through their lifecycles. A glossary at the end defines the terms both products use.

Get started with Chainguard Checks

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

Get a first check passing with the quick start, or learn each part in the step-by-step guide.

Quick start

Install chainctl

To install chainctl with Homebrew, run the following command:
```
brew install chainguard-dev/tap/chainctl
```
Or, to install it with curl on macOS or Linux, run the following commands:
```
curl -fL -o chainctl "https://dl.enforce.dev/chainctl/latest/chainctl_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/aarch64/arm64/')"
sudo install -o $UID -g $(id -g) -m 0755 chainctl /usr/local/bin/
```
If you already have chainctl, you need 0.2.386 or later. Update it with sudo chainctl update, or with brew upgrade chainctl if you installed it with Homebrew.
Sign up

In the root of a local clone of a GitHub repository that you can push to, run the following command:
```
chainctl develop init
```
The command creates your Chainguard organization, if you don’t have one, and turns on Chainguard Checks. When it asks which GitHub account to link, choose the one that owns your repository: press Enter for your own user, or enter the organization’s name. If the Chainguard App isn’t installed on that account, the command offers to open its installation page. Give the App access to your repository. If you installed it earlier and GitHub shows that it’s asking for more permissions, accept them. To sign in with an email address and password, first run chainctl config set default.social-login email.
Add a first check

Create a branch and a .chainguard/ci.yaml file with one check:
```
git checkout -b add-chainguard-checks
mkdir -p .chainguard
cat > .chainguard/ci.yaml <<'EOF'
version: 1
environment: {}
checks:
hello:
cmd: ls -la
EOF
```
The check lists the files in its working directory and needs no packages or network access, so it passes on any repository.
Open a pull request

Commit the file and push the branch:
```
git add .chainguard/ci.yaml
git commit -m "Add Chainguard Checks"
git push -u origin add-chainguard-checks
```
Then open a pull request, from the link that git push prints or on github.com.
Read the result

On the pull request’s Checks tab, wait for Chainguard Checks (presubmit) to appear and pass, which usually takes less than a minute. It’s the only check that Chainguard Checks adds for this file, because a check that passes without reporting anything gets no GitHub check of its own. Select it to see the run’s summary: its title reads All 1 check(s) passed, and its table lists hello as passed. If no check appears, refer to A pull request gets no checks.

To replace the first check with your own, refer to Replace the first check with your own. To move checks from your GitHub Actions workflows, refer to Migrate from GitHub Actions.

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 or Docker, 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:

Chainguard Checks examples

Thu, 12 Nov 2026 14:46:46 +0000

This page gives complete Chainguard Checks configurations for common kinds of projects. Copy the one closest to your project, then change its packages, commands, and network access to match. Each example passes chainctl checks validate. For what each key does, refer to the Chainguard Checks configuration reference, and for services and caches, refer to Variations, inputs, services, and caches.

Keep the following in mind when you adapt an example:

A check reaches only the hosts in its network.egress list. If your build downloads from somewhere else, such as a private package registry, add that host. Refer to Find the hosts a check needs.
A cache does nothing until your default branch’s .chainguard/ci/identities.yaml file defines cache pools, as described in Set up cache pools. The examples that use caches also run after merging, with trigger: [presubmit, postsubmit], so that runs on your default branch fill the cache that pull requests start from.
Chainguard Workspaces sessions can use these files for their packages, but they don’t start services or mount caches other than gobuild. Refer to Configure a Chainguard Workspaces session’s environment.

Java with Maven

This file installs a JDK and Maven, and runs the build’s tests with mvn verify:

Workload identities and trust in Chainguard Checks

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

A check that must authenticate to Google Cloud, AWS, Azure, or 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.

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, how to read them with the GitHub API, and how to use them to protect your branches. To watch a pull request’s checks pass, fail, and pass again after a fix, follow the tutorial Fix a failing check with Claude Code.

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. For run-ci in the whole loop, from a change through a failing pull request and its fix, follow the tutorial Fix a failing check with Claude Code.

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. To see chainctl checks failures in use, with Claude Code fixing the failure it reports, follow the tutorial Fix a failing check with Claude Code.

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.

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.

The generated chainctl checks reference has the help text of the latest chainctl release. If this page and the generated reference disagree about a command’s flags, the generated reference is right. To read the help for the version you have installed, add --help to any command, such as chainctl checks status --help. You can also type chainctl ci instead of chainctl checks. If your installation of chainctl doesn’t recognize a command or flag on this page, update chainctl.

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: