Sign and verify runs
From CLI 0.10.0, a check result can carry an Ed25519 signature (RFC 0008), and groundrule verify checks one offline. The platform side, registering keys and reading each run’s status, is in Signing keys.
groundrule keys generate
Section titled “groundrule keys generate”npx @groundrule/cli keys generate --out ~/groundrule-keysWrites two files into --out (default: the current directory):
| File | What it is |
|---|---|
groundrule-signing.key |
The private key, PKCS#8 PEM, mode 0600. Keep it secret. |
groundrule-signing.pub |
The public key, SPKI PEM. Register it in Groundrule. |
It prints the public key and its key ID, sha256: followed by the SHA-256 of the key’s raw 32 bytes, and never prints the private key. It refuses to overwrite existing files (“… exists already. Move it away, or choose another –out.”, exit code 2).
groundrule keys id groundrule-signing.pub prints a public key’s ID, as runs and the workspace name it.
Signing with check
Section titled “Signing with check”Set the private key as GROUNDRULE_SIGNING_KEY: the PEM itself, or its base64 for systems that can’t hold multi-line secrets. Then check --upload and check --write-check-run sign their result; nothing else changes.
| Option | Effect |
|---|---|
| (none) | Signs when GROUNDRULE_SIGNING_KEY is set. |
--no-sign |
Doesn’t sign, even with the key set. |
--sign |
Insists: without GROUNDRULE_SIGNING_KEY, stops with “✕ –sign needs GROUNDRULE_SIGNING_KEY. Generate a key with groundrule keys generate.” (exit code 2). |
A key that isn’t a PEM private key, or isn’t Ed25519, stops the command before the checks run (“✕ The signing key isn’t a PEM private key (or the base64 of one). …”). On success the upload line reads “✓ Uploaded, signed, to Acme Payments: …”.
In GitHub Actions, add the secret to the step:
- uses: Metricall-AI-Lab/groundrule-action@v1 with: token: ${{ secrets.GROUNDRULE_TOKEN }} env: GROUNDRULE_SIGNING_KEY: ${{ secrets.GROUNDRULE_SIGNING_KEY }}What is signed
Section titled “What is signed”The canonical JSON of the run (keys sorted, no whitespace) with two things removed: the signature field itself, and every finding’s snippet. Snippets are display aids a receiver may redact or drop, and the signature survives that. Everything else, the repository and commit, the pull request, each standard’s outcome, each finding’s file, line and message, the compliance record and the metadata, is covered.
Keyless, in GitHub Actions: --sigstore
Section titled “Keyless, in GitHub Actions: --sigstore”From CLI 0.11.0, a GitHub Actions job can sign without any key (RFC 0009): it proves its identity with the token GitHub issues to it, Sigstore turns that into a certificate valid for minutes, and the run is signed with it. The signature names the repository and workflow that produced the run, and the platform trusts it by that identity, so there is nothing to register.
permissions: contents: read id-token: write # lets the job prove its identitysteps: - uses: Metricall-AI-Lab/groundrule-action@v1 with: token: ${{ secrets.GROUNDRULE_TOKEN }} sigstore: "true"Or by hand: npx @groundrule/cli check --base origin/main --upload --sigstore. The upload line reads “✓ Uploaded, signed with Sigstore, to …”.
Things to know:
- It is opt-in and never automatic: signing records the workflow identity and the result’s SHA-256 (never the result itself, never code) in Sigstore’s public transparency log, and that is a choice for your team.
- Outside GitHub Actions
--sigstorestops with “✕ –sigstore needs GitHub Actions withpermissions: id-token: writeon the job.” Use a key there. - Not together with a key: with
GROUNDRULE_SIGNING_KEYset, pass--no-signalongside--sigstore, or the command stops with “Choose one”. - The policy: a verifier accepts the signature only if the issuer is GitHub Actions and the signer is a workflow of the run’s own repository (
https://github.com/<owner>/<repo>/.github/workflows/…). A workflow elsewhere can’t sign a run that claims to be this repository’s. - The signed payload is the same as for keys: the run without
signatureand without snippets.
groundrule verify
Section titled “groundrule verify”npx @groundrule/cli verify run.json --key groundrule-signing.pub| Exit code | Output |
|---|---|
0 |
“✓ Signature verified: signed with key sha256:…”, then the repository and commit, the pull request, the result, and the rulebook digest. |
1 |
“✕ Not verified.” and why: “The run isn’t signed.”, “The run was signed with key sha256:…, not the key given.”, or “The signature doesn’t match the run: it was altered after signing, or forged.” |
2 |
A file couldn’t be read, isn’t JSON, or isn’t a CheckRun this CLI understands. |
run.json can be a file written with --write-check-run, or the signed run downloaded from its page in Groundrule. To verify a hosted check, use Groundrule’s public key from https://api.groundrule.dev/.well-known/groundrule-keys.json.
A Sigstore-signed run needs no --key: groundrule verify run.json checks the bundle against Sigstore’s trust root and applies the policy, then prints “✓ Signature verified (Sigstore): signed by GitHub Actions, acme/payments · groundrule.yml on refs/heads/main.” When it fails, it says why: the bundle doesn’t verify, the certificate names a different identity than the run claims, or the signer isn’t a workflow of the run’s repository.