GitHub Actions

Add one step to your workflow. It skips every test that a trusted person or agent already ran against the same code, and runs the rest.

The one line

Put this after your checkout and toolchain setup steps:

- uses: PandelisZ/cryptographically-verifiable-ci-runner@v2

A few terms used on this page:

• Unit: the smallest thing vci can skip. A test file for Vitest, pytest, Minitest and RSpec; a package for Go; a test target for Rust.
• Attestation: a record, signed with an SSH key, that says "this unit passed against exactly these inputs".
• Base branch: the branch a pull request merges into, usually main. CI reads the trusted keys and the policy from its commit, never from the pull request.

@v2 follows the latest tested 2.x release. @v1 stays on 1.9.2, without keyless signing and with the full metadata fetch: read the 2.0.0 notes before moving. See pinning for stricter options.

Before you start

1. vci.toml and .vci/allowed_signers are merged to your default branch (setup guide).
2. .git-meta (written by vci init) is committed.
3. Attestations are pushed with vci push before, or together with, the branch. With a signing-key, or keylessly with oidc: true, CI also attests and pushes what it runs (see attesting in CI and keyless attestation).

A complete workflow

Save this as .github/workflows/test.yml. It is for Vitest; for other runners, swap the toolchain steps for the ones below.

name: test

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read            # read-only is enough

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0    # the base commit must be available

      # Your toolchain, at the same version as locally
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci

      - uses: PandelisZ/cryptographically-verifiable-ci-runner@v2

Setup steps for each runner

Each tab replaces the toolchain steps of the workflow above. Pin the same versions you use locally: an attestation only counts where the toolchain matches.

Environment variables. The job exports nothing for vci. A variable that must have the same value on the laptop and the runner (TZ, LANG, CGO_ENABLED) goes in vci.toml's [env] set, and vci sets it in every test process, here and where attestations are made. Every other variable of the runner (GITHUB_*, RUNNER_*, CI, ...) is removed from the tests unless [env] lists it. vci env --base-ref origin/main prints the policy the runner applies (see [env]).

      - uses: actions/setup-node@v4
        with:
          node-version: 22  # same Node major version as locally
          cache: npm
      - run: npm ci

env:
  UV_PYTHON_PREFERENCE: only-managed

      - uses: astral-sh/setup-uv@v6
        with:
          version: "0.11.7" # same uv version as locally
      - run: uv sync --locked

      - uses: actions/setup-go@v5
        with:
          go-version: "1.26.2"  # exact version used locally
      - run: go mod download

      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: "1.95.0"   # same release as rust-toolchain.toml
      - run: cargo fetch --locked

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.4.9" # exactly the Ruby used locally
          bundler-cache: true

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.4.9" # exactly the Ruby used locally
          bundler-cache: true

For several languages in one job, set up every toolchain and call the action once. Example.

What the action does

1. Installs vci in about a second: the release binary recorded in the pinned action's release/manifest.txt, its checksum verified against that file. The action never compiles vci in your CI. When no published binary fits (the action is pinned to a commit that is not a release, or the download fails) it fails at once with an error that says what to do (see prebuilt binaries).
2. Fetches attestations from origin, as vci fetch --remote origin would (it passes --fetch origin to vci ci, or to vci plan with command: plan). This fetches refs/meta/main, the git ref where attestations live by default (on a shared store there is nothing to fetch, and the remote is ignored with a warning). A contents: read token is enough. Since vci 2.0 it downloads the keys, not the values (about 2 MB for a store of thousands of attestations, whatever its history), and the plan then fetches, in one batch, the attestations it verifies and the input manifests they reference. If the fetch fails, it warns and every test runs; a value that cannot be fetched makes its unit run.
3. Runs vci plan and writes the plan to the job summary.
4. Runs vci ci: it runs every unit that was not skipped and writes an audit log. The job fails if any test fails.
5. With signing-key (or keylessly, with oidc): it attests every unit that ran and passed, and pushes the attestations to refs/meta/main, so the next commit skips each unit whose inputs did not change. See attesting in CI.

Inputs and outputs

Every input is optional.

Attesting in CI

Without a key, CI only consumes attestations, and every push to main runs the whole suite. With one, CI leaves attestations of its own behind: a push to main runs what is not attested (the first time, everything) and attests every unit that passed, so the next commit, on main or on a pull request, skips each unit whose inputs did not change.

• Commit A on main: nothing is attested yet, so every unit runs. CI attests them and pushes the attestations to refs/meta/main.
• Commit B changes src/b.ts: only src/b.test.ts reads it, so only that file runs (and is attested). Everything else skips on A's attestations, which are keyed by inputs, not by commit.
• Commit C changes only the README: every unit skips. vci ci prints nothing to run and the job never starts the test runner.

Units that fail, or that vci run would refuse to attest, still run on every commit. Each attestation expires after ttl, and its unit then runs, and is attested, again.

1. Make a key for CI

   Outside ~/.ssh: it is not yours. Trust it under its own principal:

   ssh-keygen -t ed25519 -N "" -C vci-github-actions -f vci-github-actions
   echo "github-actions namespaces=\"vci-attest\" $(cut -d' ' -f1,2 vci-github-actions.pub)" >> .vci/allowed_signers

2. Let that principal skip on main

   Keep no_skip_refs and name the principal in no_skip_refs_except. Main then skips what CI attested and still runs everything any other signer claims.

   [policy]
   no_skip_refs = ["refs/heads/main", "refs/tags/**"]
   no_skip_refs_except = ["github-actions"]

3. Store the key in an environment

   Create a GitHub Environment whose deployment branches are limited to the default branch, and store the private key as its secret VCI_SIGNING_KEY. In Settings → Environments, or:

   gh api -X PUT 'repos/{owner}/{repo}/environments/vci-attest' \
     -F 'deployment_branch_policy[protected_branches]=false' \
     -F 'deployment_branch_policy[custom_branch_policies]=true'
   gh api -X POST 'repos/{owner}/{repo}/environments/vci-attest/deployment-branch-policies' -f name=main
   gh secret set VCI_SIGNING_KEY --env vci-attest < vci-github-actions
   rm vci-github-actions      # the secret is now the only copy; keep the .pub

   Not a repository secret (gh secret set without --env): every pull request run from a branch of the repository can read those.

4. Merge steps 1 and 2 to the default branch

   Trust and policy come from the base commit. A push to main reads them from the pushed commit itself, so the push that adds them already runs, attests and publishes everything.

5. Pass the key only on pushes to main

   From a job that names the environment and may write (contents: write: vci ci --push publishes refs/meta/main with the checkout's credentials). Pull requests run a job without the key and only consume attestations.

A complete workflow (Vitest; for other runners, swap the toolchain steps for the ones above):

name: test

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  # Pull requests: skip what is attested, run the rest. No key, read-only.
  test:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # the base commit must be available
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - uses: PandelisZ/cryptographically-verifiable-ci-runner@v2

  # Pushes to main: run what is not attested, attest it, publish it.
  test-main:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    environment: vci-attest   # the only place VCI_SIGNING_KEY exists
    permissions:
      contents: write         # git-meta pushes refs/meta/main with the checkout's credentials
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - uses: PandelisZ/cryptographically-verifiable-ci-runner@v2
        with:
          signing-key: ${{ secrets.VCI_SIGNING_KEY }}
          # ttl: 14d          # lifetime of CI's attestations (at most policy.max_ttl)
          # push: true        # publish them on refs/meta/main (a failed push is a warning)

With signing-key, the action writes the key to $RUNNER_TEMP/vci-key (mode 600, never printed), runs vci ci --key ... --ttl 14d --push --remote origin, removes the key file and sets the output attested. Only test failures fail the job; a failed push is a warning.

Why an environment

A pull_request run uses the branch's own copy of the workflow, so no if: in the workflow can keep a repository secret from anyone who can push a branch. The environment's branch rule is enforced by GitHub, outside the workflow. Without it, a branch's run could sign as github-actions, and after a merge main would skip units whose code only that branch ran.

As a second line, vci ci --key attests nothing (a warning; the tests still run and nothing is pushed) when the key's principal is in no_skip_refs_except and the current ref does not match no_skip_refs. That catches a misconfigured workflow, not a branch that changes it. To attest pull request runs too, give them a different key whose principal is not in no_skip_refs_except: main never skips on its word.

What the key is shared with

Every process of the job runs as the same user, so the tests, every test dependency and every other step of that job can read the key file while it exists. Whoever copies it can make main skip any unit until its line is removed. Treat it as a credential your locked dependencies share:

• keep it in the restricted environment, one key per repository, never an organization secret;
• keep ttl short;
• rotate by replacing its line in .vci/allowed_signers on the default branch, then the secret, and do so whenever a dependency of the attested job is found compromised. Its attestations stop counting the moment the line is gone;
• list no developer or agent principal in no_skip_refs_except.

Keyless attestation (OIDC)

A job can attest without any key. With oidc: true (vci ci --oidc) it proves who it is with the OIDC token GitHub gives a job that has permissions: id-token: write, and signs through Sigstore, the way npm publish --provenance and actions/attest do: an ephemeral key, certified for ten minutes by Fulcio from the token, and an RFC 3161 timestamp per attestation. There is no secret to store, rotate or leak. Trust becomes a policy on the job's identity, committed next to .vci/allowed_signers; laptops keep SSH keys, and both kinds of attestation share the store and the policy.

1. Trust the workflow, not a key

   vci init --oidc writes both files for origin's repository, or by hand:

   # .vci/identities.toml
   [[identity]]
   principal = "github-actions"          # the name policy lists use
   issuer = "https://token.actions.githubusercontent.com"
   repository = "owner/name"
   workflow = ".github/workflows/test.yml"   # glob
   ref = "refs/heads/main"                   # glob
   event = "push"                            # optional, as are environment and runner_environment
   environment = "vci-attest"

   gh attestation trusted-root > .vci/sigstore-trusted-root.json

   The trust root lists the certificate and timestamp authorities of GitHub's Sigstore instance and of the public-good one. GitHub renews its intermediates yearly: refresh the file with the same command when vci explain names an unknown issuer.

2. Let that principal skip on main

   Name it in no_skip_refs_except as for a key, and merge both files to the default branch.

3. Attest from the main-branch job

     test-main:
       runs-on: ubuntu-latest
       if: github.event_name == 'push' && github.ref == 'refs/heads/main'
       environment: vci-attest      # optional: lets the identity require it
       permissions:
         contents: write            # vci ci --push
         id-token: write            # the OIDC token Fulcio certifies
       steps:
         - uses: actions/checkout@v4
           with:
             fetch-depth: 0
         - run: npm ci
         - uses: PandelisZ/cryptographically-verifiable-ci-runner@v2
           with:
             oidc: true

A stolen certificate is worthless ten minutes later and its key never leaves the job's memory. What stays the same: any step of the attesting job can ask for a token while the job runs, so the identity main skips on must only match runs on main (pin ref, event and, best, an environment restricted to the default branch). vci ci --oidc refuses to attest, like --key, when the job's identity signs as a principal of no_skip_refs_except on a ref no_skip_refs does not match. Verification is offline: the certificate must chain to the committed trust root, a trusted timestamp must place the signature inside the certificate's ten minutes, its repository and workflow URIs must be on the issuer's host (github.com for GitHub's issuer), and the certificate's identity must match an [[identity]]. Pull request runs and main runs of one workflow file are separate signers in the store, so a pull request's attestation never replaces main's. Anything else makes the unit run, and vci explain names the check. Details: docs/GITHUB_ACTIONS.md.

With a shared store

When attestations live on PostgreSQL or in a Turso database instead of refs/meta/main, the vci step of each job gets the store's address and credential from secrets:

      - uses: PandelisZ/cryptographically-verifiable-ci-runner@v2
        env:
          VCI_STORE_URL: ${{ secrets.VCI_STORE_URL }}
          VCI_STORE_TOKEN: ${{ secrets.VCI_STORE_TOKEN }}   # Turso; PostgreSQL's password is in the URL

• Put them on the vci step, not the job, so that the setup steps before it never see them. The tests run inside that step and can read them, so give pull-request jobs a read-only token (or a PostgreSQL role that can only read), and the main-branch job, in the vci-attest environment, one that can write.
• On a shared store vci ci stores only with --push, which the action passes with signing-key or oidc. The push writes to the store, not to git, so the job needs no contents: write for it.
• Keep fetch-depth: 0: the store names each repository's records after its first commit, which a shallow clone does not have.
• Without the action, remove the vci fetch --remote origin step that the workflow below, the examples and the workflow vci init prints all have: on any store but git-meta it stops the job with vci: error: the libsql store does not support a remote (exit 2) before any test runs. vci ci --fetch origin only warns. Give the two variables to the vci ci step, and pass --key … --push in the main-branch job only.

Step by step, with the turso and gh secret set commands: set up Turso.

Splitting a suite over jobs

A suite too slow for one runner runs as a matrix of N jobs with partition: I/N (vci ci --partition I/N, since 2.0). Each job plans the same way, then runs only its share of what the plan runs: a unit belongs to the partition its test id hashes to, so the split is the same in every job and on every machine, and every unit runs in exactly one job. What the plan skips is skipped in every job. With signing-key or oidc, each job attests and pushes its own share, and the next commit's plan skips all of it.

jobs:
  rust:
    strategy:
      matrix:
        part: [1, 2, 3]
    steps:
      - uses: actions/checkout@v5
      - uses: PandelisZ/cryptographically-verifiable-ci-runner@v2
        with:
          project: rust
          partition: ${{ matrix.part }}/3
          signing-key: ${{ secrets.VCI_SIGNING_KEY }}

A job that cannot list a project (its toolchain is missing, a transient cargo metadata failure) runs that project whole, with a ::warning: a job cannot know whether another job listed it and ran only its share, so running it whole is what keeps every unit running in some job (it may then run in more than one). Partitions balance the number of units, not their durations; a cargo unit is a whole test target, which cannot be split further. The audit log's partition names the job's share.

Pinning

The action is the verifier, so choose how far it may move:

A SHA pin must be the commit that records its release in release/manifest.txt (its message is "Record release vX.Y.Z for the action"). That is the commit v2 points to after each 2.x release, and from the first release after 1.4.0 on, the one its version tag and release page name. Any other commit of the repository has no published binary, so the action refuses it with an error instead of compiling. To find the SHA v1 points to:

git ls-remote https://github.com/PandelisZ/cryptographically-verifiable-ci-runner refs/tags/v2
# or
gh api repos/PandelisZ/cryptographically-verifiable-ci-runner/git/ref/tags/v2 --jq .object.sha

Never reference a branch: the newest commits of main are usually not released, and the action fails on them. The version tags v1.0.0 to v1.4.0 (and their release-page SHAs) point at the commit before their release was recorded in release/manifest.txt, so they run the action as it was then, which compiles vci (about two minutes) instead of downloading it. Use @v2, or the SHA it points to, instead.

Prebuilt binaries

The action downloads a release binary, which takes about a second, and never compiles vci in your CI. It installs the binary only when the pinned action's release/manifest.txt names a release built from exactly the action's own sources, a binary exists for the runner (Linux or macOS, x86_64 or arm64), and its SHA-256 equals the checksum in that manifest; because the checksums are part of the pinned action, replacing a release asset cannot change what runs. The log shows which one it installed:

using vci v1.4.0 (vci-x86_64-unknown-linux-musl.tar.gz, sha256 c906f58b...)

Otherwise the job fails at its first step, before any other work, with an error saying why. Pinned to a branch or to a commit that is not a release, it shows:

vci: this commit of the action (<ref>, sources <fingerprint>) has no published binary (release/manifest.txt records
v2.0.0 built from <fingerprint>). Use a release: uses: PandelisZ/cryptographically-verifiable-ci-runner@v2, or the
full commit SHA v2 points to (git ls-remote https://github.com/PandelisZ/cryptographically-verifiable-ci-runner
refs/tags/v2). To compile vci in this job anyway, set build-from-source: true.

Change the uses: line to @v2 or that SHA (see pinning). The other errors are in troubleshooting.

It downloads with gh release download (preinstalled on GitHub-hosted runners) and otherwise, or when gh fails, from the public release URL with curl or wget, so container jobs and self-hosted runners without gh need one of those two.

build-from-source: true is for working on vci itself, as this repository's own CI does to test sources that are not released yet. When no published binary fits, the action then compiles vci (cargo build --release, about two minutes on ubuntu-latest without a cache) instead of failing, and a failed download or checksum mismatch is a warning. It needs a Rust toolchain before the action (for example dtolnay/rust-toolchain). It caches the binary per source fingerprint, and cargo's registry and build directory per Cargo.lock and rustc version, so a commit that changes only vci's own crates does not compile the dependencies again.

Security rules

CI takes its rules from the base branch and only looks at code and attestations from the pull request:

• Pin the action. It is the verifier (see pinning).
• Never build vci from the pull request's own checkout. The pull request could change the verifier that checks it.
• Leave base-ref at its default, unless you know the ref is outside the pull request's control.
• Keep refs/heads/main in policy.no_skip_refs. Pushes to the default branch then run everything. policy.no_skip_refs_except lets only CI's own key skip there (see attesting in CI); list no developer or agent principal in it.
• Use pull_request, not pull_request_target. Fork pull requests cannot push attestations, so every test runs for them.
• Revoke a signer by removing their line from .vci/allowed_signers (or a CI identity's [[identity]] from .vci/identities.toml) on the default branch.
• Grant id-token: write only to the jobs that attest with oidc, and pin the identity main skips on to main: any step of a job with that permission can sign as its identity.
• Without the action, on git-meta, always pass --remote to vci fetch, so the checkout never chooses where attestations come from. On any other store there is nothing to fetch and vci fetch --remote exits 2: leave that step out (see with a shared store).

Who can push attestations

vci push writes refs/meta/main. Anyone with push access to the repository can write, overwrite or delete metadata there.

That is safe by design. An attestation only counts when its signature verifies against a key in the base commit's .vci/allowed_signers, and it matches the unit, repository, toolchain and inputs exactly. A deleted or overwritten attestation only makes its unit run.

Anyone who can push metadata can also turn on git-meta's auto-prune or filter rules for everyone. Pruned attestations only make their units run, and vci fetch warns about such settings in the action's log.

To limit who may write, add a repository ruleset on refs/meta/**. When CI attests its own runs, let the main-branch job's token through it.

Without the action

      # The release binary that v2 records in release/manifest.txt, checked
      # against that checksum: about a second, nothing is compiled. For a
      # strict pin, check out the commit SHA v2 points to instead of v2.
      - name: Install vci
        run: |
          git clone --quiet \
            https://github.com/PandelisZ/cryptographically-verifiable-ci-runner \
            "$RUNNER_TEMP/vci"
          cd "$RUNNER_TEMP/vci"
          git checkout --quiet --detach v2
          asset=vci-x86_64-unknown-linux-musl.tar.gz  # Linux x86_64; release/manifest.txt lists the others
          tag=$(sed -n 's/^tag=//p' release/manifest.txt)
          curl -fsSL --retry 3 -o "$asset" \
            "https://github.com/PandelisZ/cryptographically-verifiable-ci-runner/releases/download/$tag/$asset"
          grep "  $asset\$" release/manifest.txt > "$asset.sha256"  # fails if not recorded
          sha256sum -c "$asset.sha256"
          mkdir bin && tar -C bin -xzf "$asset" vci
          echo "$RUNNER_TEMP/vci/bin" >> "$GITHUB_PATH"
          echo "VCI_PY_PLUGIN=$RUNNER_TEMP/vci/py/pytest-plugin" >> "$GITHUB_ENV"
          echo "VCI_JS_PLUGIN=$RUNNER_TEMP/vci/js/vitest-plugin" >> "$GITHUB_ENV"
          echo "VCI_RUBY_COLLECTOR=$RUNNER_TEMP/vci/ruby/vci-collector" >> "$GITHUB_ENV"

      - run: vci fetch --remote origin

      - run: |
          vci ci \
            --base-ref "${{ github.event.pull_request.base.sha || github.sha }}" \
            --audit-log vci-audit.json

Troubleshooting

Run vci explain <file> --base-ref origin/main locally for the full reason a unit ran.