GitHub Integration

Planwright connects to GitHub at the organization level. Every agent commit, branch, and PR is traceable back to the objective it was executed against — and to the specific agent run that produced it.

Connecting repositories

Setup

A project links to one or more GitHub repositories.

During onboarding, Planwright installs a GitHub App on your organization and you select which repositories to grant access to. Each project can reference one or more repos — useful for monorepos where different teams own different services, or for microservice architectures where a feature spans multiple repos. Repository access can be changed at any time from Project Settings → Repositories.

One repo, many projects

Monorepos

A single repository can serve multiple Planwright projects.

If your team uses a monorepo, you can create separate projects for each service or area and link them all to the same repo. Planwright scopes objectives, agent runs, and audit records to the project level — not the repo. This means the platform team and the product team can have entirely separate boards, workflows, and initiative histories even though every agent commit lands in the same repository.

Branch strategy

Git workflow

Planwright supports two branch strategies: branch-pr and direct.

branch-pr

Default for most objectives

The agent creates a branch named planwright/obj-{slug}-{objectiveId}, commits all changes to that branch with per-task commits, and opens a GitHub PR when complete. The PR body must include the Planwright-Objective trailer so Planwright can link the diff. Humans review the PR before accepting the objective.

direct

For low-risk or docs work

The agent commits directly to the current branch with no PR. Still requires the commit trailers. The human reviews the objective in Planwright's Acceptance lane rather than through a GitHub PR. Set via project settings or overridden per-objective.

PR linking

Traceability

Every PR opened by an agent must include a Planwright-Objective trailer in its body.

When Planwright receives a GitHub webhook for a PR, it scans the PR body for the trailer and links the PR to the objective automatically. Without this trailer, the PR is treated as unlinked work and will not appear in the objective's agent run history or the audit chain.

Required in every PR body

Planwright-Objective: <objectiveId>

Commit traceability

Audit chain

Every agent commit must include both trailers — one for the objective, one for the agent run.

Planwright appends both trailers to every commit it attributes. The Planwright-Objective trailer links the commit to the outcome being pursued. The Agent-Run trailer links it to the specific execution session. Together they form an immutable, hash-chained audit record — signed with an Ed25519 key stored in AWS KMS — that satisfies the 2026 AICPA SOC 2 Trust Services Criteria for AI-generated code.

Required on every agent commit

Planwright-Objective: <objectiveId>
Agent-Run: <agentRunId>

Agent workflows with GitHub

End-to-end

The full loop from objective claim to merged PR.

1.
Claim — Agent calls planwright_claim_objective. Planwright returns the branchStrategy, objectiveId, and agentRunId.
2.
Branch — If branchStrategy is branch-pr, agent creates planwright/obj-{slug}-{objectiveId} and pushes it.
3.
Commit — Agent makes changes, commits with both required trailers, and pushes after each task.
4.
PR — Agent opens a PR with the Planwright-Objective trailer in the body. Planwright links it automatically via webhook.
5.
Review — Human reviews the PR and the objective in the Acceptance lane. Accepting the objective moves it to Done.

← Your First Project Tracker Integrations →