Troubleshooting

Errors you may meet and what they mean.

Messages you may see, what they mean, what to do. Start with secretree doctor: it runs every check below and prints the fix next to each failure.

Installation

fatal: Unable to find remote helper for 'secretree' git cannot see git-remote-secretree on its PATH. Run secretree install-helper --dir <a directory on PATH> (for example /usr/local/bin), or put the secretree binary itself in such a directory and run install-helper again. GUI git clients often have a shorter PATH than your shell.

A Keychain dialog appears on every command (macOS) Click "Always Allow" once for secretree and, separately, for git-remote-secretree (macOS treats the symlink as a second program).

keys for vault … are not in the file (…) on Linux No Secret Service was available, so keys went into the file store under ~/.config/secretree/keys. Install libsecret-tools to use the Secret Service from now on; existing file-store keys are still read when SECRETREE_KEYSTORE=file.

Vault and sync

vault rejected the push: another writer appended a generation first Someone pushed between your fetch and your push. git fetch, merge or rebase, push again; exactly like any other remote.

! [remote rejected] main -> main (vault rejected (someone pushed first; fetch and retry)) The same situation seen through git.

existing chain failed verification, refusing to append The vault on the remote does not verify: a broken hash chain, a bad signature or an unreadable manifest. secretree will not write on top of it. Run secretree verify --quick to see which generation fails. If the host rolled the vault back, the last good state is what the chain shows; if a blob is corrupt, restore from the previous generation and start a new full one with backup --full.

generation 000003: opaque (predates this key) This device's key was added after that generation was written, so it cannot read it; the signature and chain link were still verified. Everything from the full generation written at your approval onward is readable, including the whole git history.

the vault holds several repositories; pass --repo-id Use secretree clone <vault>#<repo-id> or git clone secretree::<vault>#<repo-id>. secretree restore without --repo-id lists them with their labels.

vault is empty; run secretree init first The remote has no commits. init bootstraps it; clone and the helper need an existing vault.

recovery kit is for vault X but the remote holds vault Y Wrong kit for this remote.

Pull requests

cannot merge: needs 1 approval(s) of 900c2a69, has 0 Approvals count only for the current head commit. After a new push, ask for a new approval.

cannot merge: required check "ci" has not run for 900c2a69 No runner has processed this commit yet. Start one with secretree runner --once on a machine that holds a key.

cannot merge: this device is an agent; a person has to merge Agent members cannot merge. Merge from a person's device or the UI.

branch feature is not on the vault yet: git push origin feature pr open needs the head branch pushed first.

A line comment shows as "outdated" The line it was anchored to changed or was removed in a later push. The comment stays in the conversation with the commit it referred to.

Runner and deploy

no pipeline: add .secretree/ci, a ci make target, or run the runner with --cmd The runner found nothing to execute in that commit.

deploy: waiting for check "ci" on 4ebfacfe (with -v) The branch tip has no green check yet; the deploy agent waits. Use --require-check "" to deploy without a gate.

The job ran but secretree pr comment inside it failed with not initialised Use secretree -C "$SECRETREE_REPO_DIR" …: the job runs in a throw-away worktree, the runner's clone holds the configuration.

Windows notes

The helper is a copy named git-remote-secretree.exe; keep it next to secretree.exe. Pipelines, hooks and watch --exec commands run through cmd.exe. schedule and ui --install are not available; use Task Scheduler. Keys use the file store under %APPDATA%\secretree.

Getting help

Open an issue at github.com/andraspalinkas/secretree with the command, its output and secretree -v status. For anything security-related, use a private advisory instead.