Secret protection

AgentGit can protect secrets before conversation bytes enter its Git history, then check outgoing history again before publication. These steps have distinct roles: registering a literal protects future saves, while a publication scan checks what the repository would send.

Register a secret before saving

agit secrets add staging-db-password
agit secrets list
agit secrets status

The add command prompts for the value without echoing it. Give the record a label that does not itself contain sensitive information. For automation, pass the secret through stdin rather than command-line arguments:

printf '%s' "$SERVICE_TOKEN" | agit secrets add service-token --stdin

Supply SERVICE_TOKEN from your secret store and disable shell tracing. list and status show labels, opaque IDs, and health; they do not reveal values.

At agit commit, registered literals and protected repository candidates are projected into opaque {{AGIT_SECRET_V1:...}} placeholders before Git object IDs are formed. The original mapping stays encrypted on this device. Register low-entropy values, such as an internal hostname, that heuristic detection might otherwise miss. --allow-short permits a short literal that would normally be rejected; such rules can match unrelated content, so use a longer literal when possible.

Review a repository’s protection policy

These commands need the Agent repo checkout path, not your project’s code folder or a Hub slug. Obtain it first:

agit repo path alice/my-project@first-task

Copy the printed path into AGENT_REPO_PATH in the commands below:

agit secrets review --repo AGENT_REPO_PATH
agit secrets allow RECORD_ID --repo AGENT_REPO_PATH
agit secrets unallow RECORD_ID --repo AGENT_REPO_PATH
agit secrets block add internal-hostname --repo AGENT_REPO_PATH

Use review to inspect candidate labels and IDs. allow marks a heuristic false positive so it is not projected in future saves; unallow restores its protection. An explicit block registers a repository-local value through a hidden prompt and takes precedence over a heuristic allow. Do not run both policy-changing examples unless you intend both decisions.

Allowing a candidate does not rewrite existing commits or delete the reverse mapping needed to restore older placeholders. Removing a vault record with agit secrets remove RECORD_ID is irreversible: placeholders tied to that record can no longer be hydrated from it.

Check before publishing

agit scan alice/my-project@first-task --secrets
agit push alice/my-project@first-task --dry-run

The secret scan checks the repository’s publication surface, including retained evidence; selecting an event does not limit it to only that event. A normal push checks outgoing history and refuses suspected secrets or an incomplete scan. Read the reported reason; no findings is not sufficient when scanning was incomplete. Hub publication checks remain independent of local exceptions.

Registering a value now does not erase it from earlier commits. Removing an event with agit revert changes the VIEW while retaining evidence. Rotate a credential that has already been exposed, then follow the scan’s instructions. See publication checks.

Review sensitive content

agit scan TARGET --sensitive asks a supported installed runtime to review the selected committed VIEW for disclosure risks. It is separate from deterministic secret detection and does not apply findings automatically:

agit scan alice/my-project@first-task#3 --sensitive --json

This review currently supports compatible Claude Code installations selected by runtime.default. Other runtimes report that review is unavailable. The native runtime can use a remote model provider, so this operation is not necessarily offline. Only the selected committed context is reviewed; unsaved turns and working files are excluded. An unavailable or incomplete review is not a clean bill of health. Inspect complete, findings, and the exit code.

Keystore access and another machine

The default secrets.keystore=os uses the operating system’s credential store. If macOS Keychain requires authorization, rerun the affected command in a terminal in your macOS login session and approve access there. A noninteractive agent process cannot open that authorization dialog. Changing keystores does not repair access to an existing vault key.

On Unix systems without a desktop credential service, a device can explicitly select secrets.keystore=file; its keys are protected by filesystem permissions under AGIT_HOME/keystore/. Backups containing those keys and encrypted records can restore the secrets. Treat those backups accordingly. AgentGit does not silently fall back between stores.

Protected history can be shared without its local reverse mappings. Another machine does not receive those mappings through push or clone. See configuration and agit doctor to inspect the selected keystore and its availability.