Git & credentials

Branches carry the work: naming, PR steps, and how runs get permission to push.

Peractor treats git as the system of record. Each run works on its own branch; the branch history is the run history, which is what makes runs reviewable, resumable, and reproducible.

The work branch

A run's branch is named from its task — peractor/DRE-231-add-login when the task has a tracker key, peractor/<title>-<id> otherwise; a start-over appends -r2, -r3…

The branch is the only carrier of state between phases. Each phase starts from what the branch holds, and the branch only advances when a phase completes cleanly — a crashed or aborted attempt leaves it untouched. Workspaces and agent sessions are disposable; approve a gate a week later and the next phase picks up exactly where the branch is.

Git steps

Workflows drive the VCS with git steps — open-pr (optionally as a draft), ready-pr, merge (merge / squash / rebase) — and they run at their declared position, not batched at phase end: the sandbox commits and pushes the work so far, the control plane performs the VCS action with its own credentials, and the step's result lands back in the transcript. So "open a draft PR, then keep working" behaves exactly as written.

A git: merge step goes through the normal VCS APIs, so branch protection still applies — Peractor's gate controls the workflow, your repo rules still control the merge.

How runs get push access

Sandboxes have no ambient git identity. When a run needs to push, Peractor resolves a credential in this order:

  • Settings → Git access — a per-organization token or SSH key (with optional host filter) you connect in the app. Works with GitHub, GitLab, Bitbucket, and self-hosted remotes. This always wins when configured.
  • The Peractor GitHub App — install it once and every run gets a short-lived token scoped to exactly the repository it works on. The App also opens and merges the pull requests. Recommended for GitHub.

With neither, a run that must push fails with a clear message rather than degrading silently. The resolved token is also available inside the sandbox as GITHUB_TOKEN/GH_TOKEN, so command steps can call gh or install private packages.

Setting up? See Getting started step 3, or Self-hosting for the GitHub App environment variables.