Skip to the content

Approve a CI job's risky step from your laptop

Mark the commands a CI job may wait on a person for, and approve the job's request from the console with your passkey, for exactly that call, once.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Have Central Lite attest your CI jobs, mark the commands that may wait for a person with approval: remote, list the passkeys that may approve them, and approve a job's request from the console with your passkey: the job's agentgarmd checks your signature itself and lets exactly that call through, once.

1. Let Central Lite attest the job

A remote approval needs an attested job: the job proves who it is to your Central Lite with its GitHub Actions OIDC token, and Central Lite checks it against an allow-list before it issues the job an ephemeral certificate. On the Central Lite host, accept GitHub's issuer (the default) and allow the workflow by its numeric owner and repository ids and its job_workflow_ref; names are refused, and the token's sub is never matched. garm-central ci trust prints the central-trust line the job needs to check Central Lite before it sends its token; it is not secret. A self-hosted runner's certificate lives 6 hours unless garm-central ci config --max-job-hours sets 1 to 120 (GitHub-hosted runners always get 6), and garm-central ci jobs lists the jobs Central Lite has attested, newest first.

In the workflow, the AgentGarm action takes central-url and central-trust, and the job must grant permissions: id-token: write. The action is not published yet; beta customers get it on request (see AgentGarm in CI). A token Central Lite refuses fails the job, so no agent runs unattested.

garm-central ci issuer add
garm-central ci allow add --repository-owner-id 1234567 --repository-id 7654321 --job-workflow-ref my-org/my-repo/.github/workflows/agents.yml@refs/heads/main
garm-central ci show
garm-central ci trust

2. Mark the steps that may wait for a person

An attested job runs only the policy Central Lite publishes; it never reads agents.d, and it fails if no bundle is in force. In a CI job agentgarmd runs with the ephemeral profile, which turns every ask into a deny, whatever the policy's own profile. An ask rule marked approval: remote is the exception: it waits for a remote approver instead. It applies to command rules only, and not with run_as: agentgarmd.

Here terraform apply waits for an approver. sudo is an ask without approval: remote, so the ephemeral profile turns it into a deny. Commit the policy to the repository Central Lite pulls and publish it with a committer's attestation, as every bundle.

security_boundaries:
  execution:
    rules:
      - ask: { exec: [terraform], args_match: "apply*", approval: remote }
      - ask: { exec: [sudo], presence: required }
garm-central policy publish

See also

Govern agents on a headless server or container

Check what a server or container offers, set a policy to the headless profile so every ask is denied instead of waiting, and test it before you install it.

3. List the passkeys that may approve

Approvers are listed in your org root metadata, which the job verifies against central-trust, so Central Lite's online keys cannot add one. Create a passkey for Central Lite's host name and write its credential id and its ES256 public key as an uncompressed SEC1 point (65 bytes, starting 04), both in hex, into an approvers file: {"rp_id": "<host>", "origins": ["https://<host>[:port]"], "keys": [{"id": "<name>", "credential_id": "<hex>", "public_key": "<hex>"}]}. A COSE or SPKI export of the key is refused. Each id is lowercase letters, digits and ._@-, starting with a letter or digit, at most 64 characters. Central Lite refuses a file that does not allow its exact own origin, port included when it is not 443, since approvers answer on its console, and an admin's sign-in passkey never approves: keep the approver passkey separate.

On Central Lite, garm-central root lite --approvers signs the set into the next metadata version with Lite's own root key. A job takes the set in force when it starts.

The same set approves fleet kill orders: two of these keys sign each order and each lift, and every node checks them (Stop agents across a fleet). A kill order does not reach CI jobs, though: its blast radius leaves CI nodes out as not covered, and a job's own channel refuses kills, so stop a job from your CI provider.

garm-central root lite --approvers approvers.json
garm-central approver list

See also

Stand up Central Lite

Set up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup.

4. Read what the job asks

When the agent runs a command the rule marks, agentgarmd sends a request to Central Lite and denies the call for now; the agent is told awaiting remote approval: retry. The request lives 10 minutes, and the call is allowed only on a retry after it is approved. At most 3 requests wait per task and 16 on the runner; Central Lite holds at most 8 pending per node.

Sign in to the console as an admin and open Approvals. Each request is a card marked Remote approval, with the node, the time left, and the command as the node wrote it, secrets replaced and at most 512 characters, under “A job on this node asks to run exactly this:”. The text crosses to Central Lite. Under the non-monitoring compliance profile no ask is sent: it is denied on the runner.

5. Approve with your passkey, or deny

Choose “Approve with an approver passkey” and confirm with your passkey; user verification (a PIN or a biometric) is required. Central Lite checks the assertion and relays it signed, and the job's agentgarmd verifies your signature itself against the approver set before the approval counts. The agent's next try of exactly that call is allowed once, and its decision record names you and the request; a later try asks again.

Answering needs the owner, admin or security role in the console, and still the approver key: a role never approves. The first time a key answers, Central Lite records the admin signed in as its holder, and from then on refuses that key from anyone else's session (who holds each approver key).

“Deny” takes an optional reason, and the call stays denied until the request expires. Doing nothing leaves it denied too: Central Lite unreachable, no approver set (the agent is told “this CI job has no remote approvers”), a refused signature and an expiry all keep the call denied.

6. Know what an approval is worth

Under an offline org root of two or more keys, a compromised Central Lite cannot approve alone: it can neither forge an approver's signature nor add an approver. Under Central Lite's single software root it can, since whoever controls Central Lite's host could list an approver of their own. Approvals rate B under an org root of at least two keys whose custody the org declares offline, and C under Central Lite's root; every routed and allowed call records the root's custody. No production org root exists yet: the ceremony that creates one has not been held.

To stop an approver, garm-central approver revoke puts the key on the next revocation list; an approval it already gave allows nothing more. When your identity provider deprovisions a key's holder through SCIM, Central Lite refuses that key's approvals at once, and revokes it after 7 days, or at once when the holder is deleted, unless too few keys would be left for a kill order. In the job, agentgarm status shows the ci policy line: IN FORCE with the bundle's version, or why every task is refused.

garm-central approver revoke --key-id <approver id> --reason "left the team"
agentgarm status