Verifying capsules in CI

Every local command is non-interactive and exits 0 on success. patcharc verify is the one command whose exit code reflects the content of a file, which makes it a natural gate.

Verify a capsule in a pipeline

# .github/workflows/verify-capsule.yml
name: verify-capsule
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install patcharc
        run: curl -fsSL https://patcharc.dev/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Verify every capsule committed with this change
        run: |
          shopt -s nullglob
          for f in capsules/*.parc; do
            patcharc verify "$f"
          done

verify exits 1 and prints each issue when a signature, hash, size, path, or compression check fails:

$ patcharc verify capsules/arc_8f2c1d4a9b.parc
✗ arc_8f2c1d4a9b is INVALID
  - file evidence/git/diffs/a1b2c3d.patch: sha256 mismatch

Capsules are .gitignored under .patcharc/ by default; if you want CI to verify them, copy the .parc somewhere tracked (as above) or upload it as a build artifact.

Record an Arc in CI

You can run the loop headlessly. init and start --detach need no input:

$ patcharc init --force
$ patcharc start --detach "CI build $GITHUB_RUN_ID"
# ... steps that commit ...
$ patcharc stop
$ patcharc verify .patcharc/capsules/*.parc

--force is needed when a .patcharc/ directory is already present in the checkout; it rotates the signing key, which is what you want on an ephemeral runner.

Sharing from CI

There is no CI token flow in 0.2.0. patcharc share needs ~/.patcharc/credentials.json, which is written by the interactive device flow. If you must upload from a pipeline, place a credentials file produced on a workstation into $HOME/.patcharc/credentials.json (mode 0600) from a secret; the refresh token in it rotates on every use, so the stored secret goes stale after the first run. A dedicated non-interactive token is on the roadmap; until then, prefer sharing from the developer's machine.

PATCHARC_CLI_API_URL overrides the API base URL if you run a private deployment.

Exit codes

See Exit codes and output.

Not available yet

• A GitHub Action. The actions/patcharc-action directory in the repository is a placeholder.
• Machine-readable output. There is no --json flag; parse the human output or the capsule's JSON files instead (unzip -p capsule.parc evidence/summary/review.json).
• Attestation formats. A .parc is not an in-toto statement. Treat it as a change-process record that sits next to build provenance, not as a replacement for it.