Configuration

Two committed files control vci: vci.toml sets policy, and .vci/allowed_signers says whose attestations count. A repository whose CI signs keylessly (vci 2.0) adds .vci/identities.toml and the Sigstore trust root.

vci.toml

This is a complete file for one Vitest project. vci init writes a longer, commented version of it.

project = "."          # project dir, relative to the repo root
adapter = "vitest"     # or "pytest", "go", "cargo", "rails"

[policy]
# Nothing is skipped on these refs: every merge gets a full run.
no_skip_refs = ["refs/heads/main", "refs/tags/**"]
# ...except what CI's own key attested (see GitHub Actions).
# no_skip_refs_except = ["github-actions"]

[env]                          # every variable in no list is removed
set = { TZ = "UTC" }           # vci sets these everywhere
hash = []                      # from the machine; a change re-runs
ignore = []                    # visible, never hashed: secrets go here

Every key you leave out takes its default, listed below. Unknown keys are errors.

The rest of the file is four tables, explained in order below: [policy], [env], [[inputs]] and, for a repository with several projects, [[projects]].

[policy]

When an attestation is good enough, and where nothing is skipped.

Removed: rails_allow_db was removed in 1.4.0, because vci no longer manages the Rails test database: a database server configured for the test environment needs no policy (see Rails). The key is a deprecated no-op kept for compatibility. A vci.toml that still sets it, at the top level or in a project, parses, so a base commit that has it does not make every test run; it has no effect, and vci run and vci plan print one warning. Remove it.

Platform overrides

Tighten the platform rule for some files and leave the rest on "any". An entry sets platform, libraries, or both:

[[policy.platform_overrides]]
match = ["src/native/**"]   # project-relative globs
platform = "exact"

[[policy.platform_overrides]]
match = ["test/images/**"]
libraries = "exact"

Overrides only tighten: the strictest of [policy] and every matching entry applies.

macOS to Linux

Under platform = "any", a Rails file that loaded libvips (any file that boots an app with Active Storage and image_processing) still runs on a Linux runner: Homebrew's libvips is a different file from apt's. The same happens when the SQLite, libyaml or time zone data versions differ, or, for pytest, the interpreter's SQLite or OpenSSL. To skip those files across platforms:

[policy]
platform = "any"
libraries = "any"

Install libvips on the runner as well; under "any" it is matched by name, but it must still be loaded there. Everything else is still compared exactly: the Ruby or Python version, every gem or distribution in the lockfile, the inputs and the declared environment. By setting it you state that these libraries behave the same on both platforms for your tests. vci explain lists every difference the policy accepted.

[env]: environment variables

Environment variables can change a test's result, so vci decides which ones a test sees and hashes the ones that matter. The policy is three short lists, plus a short built-in list per runner; every other variable is removed from the test processes, in vci run and in CI alike:

[env]
# vci sets these in every test process, on every machine
set = { TZ = "UTC", LANG = "C.UTF-8" }
# taken from the machine and hashed: another value re-runs the test
hash = ["DATABASE_URL", "FEATURE_*", "!FEATURE_DEBUG"]
# taken from the machine, never hashed, never a reason to re-run
ignore = ["GITHUB_TOKEN", "AWS_*"]

[[env.files]]            # additions for matching test files
match = ["src/db/**/*.test.ts"]
hash = ["PGDATABASE"]
ignore = ["PGPASSWORD"]

Patterns are exact names, * wildcards, and a leading ! to exclude. Exclusions win. Matching is case-sensitive. set takes exact names and string values (write "1", not 1). The variables an [[env.files]] entry names reach every test of the project; only the matching files hash them up front.

Which variables reach the test

Precedence when lists overlap: set, then hash, then ignore, then the built-in lists. vci env prints the effective lists of each project and what each variable is on this machine; vci env --base-ref origin/main shows where the base policy (the one CI uses) differs.

CI, NO_COLOR and FORCE_COLOR are removed unless listed. Only the values vci itself sets for a runner win over set: RAILS_ENV=test and the collector's RUBYOPT, a node:test script's NAME=value assignments, and the fresh TMPDIR of Go, Cargo and Rails processes.

Seeing the policy: vci env

vci env [--base-ref REF] [--project NAME] [--format text|json] prints, per project, every variable the lists name, its class, where the rule comes from and what it is on this machine. It runs nothing.

$ vci env --project web
project web (node-test): env config ff29623f04f0
  VARIABLE        CLASS            SOURCE                   HERE
  LANG            set              vci.toml set             "C.UTF-8"
  TZ              set              vci.toml set             "UTC"
  FEATURE_*       hash             vci.toml hash            pattern: 1 here
  FEATURE_SEARCH  hash             vci.toml hash            present (5d2a6bf0fba6)
  NODE_ENV        hash             test script              present (4878ca0425c7)
  SCCACHE_*       ignore           vci.toml ignore          pattern: 1 here
  SCCACHE_DIR     ignore           vci.toml ignore          present
  HOME            built-in ignore  built-in (every runner)  present
  PATH            built-in ignore  built-in (every runner)  present
  built-in, not set here:
    LC_ALL LC_MESSAGES NODE_OPTIONS UV_THREADPOOL_SIZE ...
  present here, removed from the tests (recorded as absent if a test reads one):
    CI GITHUB_TOKEN

With --base-ref origin/main a BASE column shows where the base commit's policy, the one CI judges with, differs (= where it does not), and the header says base policy differs or same as base. When a test runs in CI because of the environment, vci explain names the variable and its class, never its value: env:FEATURE_SEARCH (hash).

Old names (vci 1.5 and earlier)

The old names still work, at the top level, per project and in [[env.files]], with one warning that names each key to rename. Giving both an old and a new name in one table is an error. Renaming alone re-runs nothing, but every attestation made before vci 1.6.0 fails the env-config check once and its test re-runs, because what is hashed changed.

Secrets

vci never stores values, only their BLAKE3 hashes. But anyone who can read the attestations can brute-force the hash of a low-entropy value. Put secrets in ignore, not in hash, and never in set (its values are in vci.toml). vci run warns when a hash name matches *TOKEN*, *SECRET*, *PASSWORD* or *KEY*.

Built-in lists

Each runner's built-in lists are short: the few variables its runtime reads natively that change results (built-in hash: they reach the test and are hashed when present) and the ones its toolchain needs to work (built-in ignore: they reach the test and are never hashed, since 2.0.2 not even when a test reads one; hash opts one in). Every runner adds TZ to the first and PATH, HOME, USER, SHELL, TMPDIR, TEMP, TMP, TERM, VCI_* (and Windows' startup variables) to the second.

Everything else of a runner's families is removed unless listed: GOMAXPROCS, NODE_PATH, RUST_BACKTRACE and RUST_LOG (set = { RUST_BACKTRACE = "1" } for backtraces), Minitest's SEED and TESTOPTS, RSpec's SPEC_OPTS, RAILS_MASTER_KEY, ... A removed variable is unset where the test was attested and in CI, so it cannot make the two runs differ. Rails processes always get RAILS_ENV=test from vci. The full tables, with a reason per line, are in docs/ENV.md.

[[inputs]]: extra inputs

Declare files a unit depends on that vci cannot find on its own. Any adapter accepts this; the cargo adapter needs it for tests that read outside their package directory.

[[inputs]]
# unit ids (globs)
match = ["crates/b#test:*"]
# files, relative to the project dir (globs)
extra = ["testdata/**", "shared/config.json"]

• A glob without wildcards names a file, a directory (walked), or a path that must stay absent.
• With wildcards, every matching file is hashed and each directory walked is recorded as a listing, so a new matching file is noticed.

[store]: where attestations live

Since 2.8.0. Attestations live in git-meta (the default: refs/meta/main of a git remote), a local SQLite file, a shared PostgreSQL server, or a libSQL database (Turso; read directly or through a local replica). The environment chooses first: VCI_STORE (git-meta, sqlite, postgres, libsql), else the scheme of VCI_STORE_URL, else [store] in the working tree's vci.toml (backend, else the scheme of url), else git-meta. vci store info says which one a repository uses and where each setting came from. Which store to pick, and step-by-step setup for Turso, PostgreSQL and SQLite: choosing a store.

[store]
backend = "sqlite"          # "git-meta" (default) | "sqlite" | "postgres" | "libsql"
timeout = "30s"             # one statement or wait; connect_timeout = "5s" too

[store.sqlite]
path = "vci-store.sqlite"   # relative to the git common directory (the default)

[store.postgres]            # tuning only
schema = "vci"
namespace = "acme-web"      # default: the repository id

[store.libsql]
replica = true              # read a local replica, synced as each command reads it
path = "vci-store.libsql"   # the local file or the replica (the default)

A shared server can be named in vci.toml, with the command that prints its token, so that developers and agents export nothing:

[store]
backend = "libsql"
url = "libsql://vci-vex-composal.aws-eu-west-1.turso.io"   # never a credential; VCI_STORE_URL wins
token_command = ["com", "secrets", "get", "vci-store-token", "--org", "vex"]
# or ["op", "read", "op://Engineering/vci-store/credential"] (1Password),
# ["cat", "/path/to/token"] (weaker: a file on disk), or "a | pipeline" (sh -c)

• Never a credential. Every checkout, a pull request's included, carries vci.toml: a [store] url with a password, a token or a #fragment is refused, and so are host, user, password, dbname, token and authToken under [store.postgres] and [store.libsql]. In CI the URL goes in VCI_STORE_URL and a libSQL token in VCI_STORE_TOKEN, secrets that vci keeps out of every environment it builds for a test; they win over url and token_command, which then does not run while VCI_STORE_TOKEN is set and not empty (GitHub gives a secret that does not exist, as in a fork's pull request, as an empty string, which vci treats as unset).
• A test that goes looking can still read them. The environment vci started with, and that of the CI step's shell that set them, stay readable to every process of the same user (/proc/<pid>/environ on Linux, ps eww on macOS), and vci cannot hide them there. So a CI job that runs untrusted pull-request code holds no store credential, or a read-only one (turso db tokens create <db> --read-only; a PostgreSQL role with SELECT only), and only trusted jobs (the default branch, or pull requests from the same repository, whose authors could change the workflow anyway) hold one that can write.
• A token from the environment goes only to a URL from the environment. VCI_STORE_TOKEN with the URL from [store] url is refused (set VCI_STORE_URL too): otherwise a pull request could point CI's secret at its own server.
• token_command (an array, run directly; or a string, run with sh -c) runs only when a command first reads a store that needs a credential, once per vci process, in the repository's top level, with your own privileges (the trust of running the checkout's tests) and without VCI_STORE_URL, VCI_STORE_TOKEN or VCI_STORE. It must print the token alone on one line; after 60 s it is stopped with everything it started (its process group). It cannot prompt on the terminal, so sign in first (com login, op signin). A command that fails makes the store unavailable: the plan runs everything, saying what happened (exited 1, printed nothing, …) and naming the command, but never showing what it printed, on standard output or standard error, which may hold the token: run the command yourself, in your own terminal, with its standard output discarded (com secrets get vci-store-token --org vex > /dev/null) to see its error. That discards the token a command that works prints on standard output; standard error still shows, and a wrapper or a pipeline stage can log the token there, so never have an agent run it. Since 2.8.1 the message says to discard standard output and quotes the command for a shell, so it can be pasted as it is. 2.8.0 says only to run the command, and leaves most characters a shell reads specially without quotes (&, ;, |, #, glob characters), so a shell could end the command, or start a comment, before the redirect: with 2.8.0, copy the command from vci.toml and put every argument in single quotes, or run a string token_command as sh -c '<the string>' > /dev/null (each ' in it written '\''), so that the redirect covers the whole command. vci store info names the command, never the token. It also supplies a PostgreSQL password the URL does not carry.
• Review url as you would token_command. On your machine the token the command prints is sent to whatever [store] url names, and both come from the checkout: in a pull request that changes either, any vci command that reads the store (vci plan too, before any test runs) sends your token to its server or runs its program. In a checkout you have not reviewed, run vci with VCI_STORE=git-meta, which ignores both and never runs the command.
• Never an input. Switching store invalidates no attestation; the new store starts empty, so its units run once.
• Roll out through the environment first. A vci before 2.8.0 rejects a vci.toml with [store] and runs every test, so add it only once every runner and developer has 2.8.0.
• On PostgreSQL and a libSQL server, vci ci stores only with --push. Details: where attestations live.

Several projects in one repository

Replace project and adapter with a list of [[projects]]. The top-level [policy] and [env] become shared defaults. A key in a project's own table replaces the top-level key for that project only (a project's set replaces the whole top-level set; it does not merge):

[policy]
max_ttl = "30d"

[env]
set = { TZ = "UTC" }

[[projects]]
name = "web"           # unique: letters, digits, '.', '_', '-'
path = "web"
adapter = "vitest"

[[projects]]
name = "api"
path = "services/api"
adapter = "pytest"
[projects.policy]
platform = "same-os"
[projects.env]
hash = ["APP_*"]

• Test ids stay repo-relative paths, so they are unambiguous across projects.
• vci run, plan, ci and explain work across all projects.
• vci run FILE only needs the toolchain of the project that file belongs to.
• A project can also set its own runner, rails_inputs and ignore_inputs, and its own inputs = [...], which replaces the top-level [[inputs]] list.

.vci/allowed_signers

The trust root: the keys whose attestations CI accepts. It uses OpenSSH's allowed_signers format, one line per person or agent:

alice@example.com namespaces="vci-attest" ssh-ed25519 AAAAC3Nza...
build-agent namespaces="vci-attest",valid-before="20270101" ssh-ed25519 AAAAC3Nza...

• namespaces="vci-attest" limits the key to vci attestations.
• valid-after and valid-before are honoured. Give agent keys an expiry.
• cert-authority entries are rejected.
• To revoke a signer, remove the line on the default branch. Attestations by that key stop being accepted at once.

.vci/identities.toml

Since 2.0. Which CI jobs may sign keylessly (vci ci --oidc, the action's oidc: true), and as which principal. A GitHub Actions job proves its identity with its OIDC token, Sigstore's Fulcio certifies it, and vci matches what the certificate says against these entries. The principal then counts exactly like an allowed_signers one in no_skip_refs_except and attest_on_any_ref. vci init --oidc writes a first version.

[[identity]]
principal = "github-actions"                           # the name policy lists use
issuer = "https://token.actions.githubusercontent.com" # exactly
repository = "owner/name"                              # exactly; no glob
workflow = ".github/workflows/test.yml"                # glob: the file the signing job is defined in
ref = "refs/heads/main"                                # glob
event = "push"                                         # optional, glob
environment = "vci-attest"                             # optional, glob: the job's GitHub Environment
runner_environment = "github-hosted"                   # optional, glob

[[identity]]                                           # pull requests: skip on each other's runs, not on main
principal = "github-actions-pr"
issuer = "https://token.actions.githubusercontent.com"
repository = "owner/name"
workflow = ".github/workflows/test.yml"
ref = "refs/pull/*/merge"
event = "pull_request"

• Every field present must match; * and ? do not cross /, ** does. workflow is the path in the repository, or owner/name/<path> for a reusable workflow of another repository. The first matching entry names the principal.
• Pin the identity main skips on to main (ref, event, best an environment limited to the default branch): any step of the attesting job can request its token and sign as it.
• Unknown keys are errors. An invalid file is a warning, and every keyless attestation then fails: those units run.
• To revoke an identity, remove its entry on the default branch.

.vci/sigstore-trusted-root.json sits next to it: the certificate and timestamp authorities keyless signatures must chain to, as gh attestation trusted-root prints them. GitHub renews its intermediates yearly; refresh the file with the same command when vci explain says the certificate's issuer is no authority of the trust root. Without it, keyless attestations fail and their units run. Verification is offline. Details: keyless attestation.

.git-meta

Names the remote that attestations are exchanged with. vci init writes url: with your origin's URL; pass --meta-url URL to keep metadata in a separate repository.

CI should name the remote itself, as the action does with vci fetch --remote origin, so a pull request's .git-meta never chooses where attestations come from. See where attestations live.