Quickstart

Give one agent one repo, one branch pattern, and one approval point.

Connect GitHub, create an Agent identity, grant a review-branch boundary, keep risky PR actions in Ask mode, then rotate or revoke the identity and inspect Activity evidence.

Before You Start

Use this quickstart when Claude, Codex, Cursor, or a hosted session should inspect a repo, edit in a sandbox, run tests, and push only to a review branch. The PR stays the human review surface, and merge is separate authority.

If your first task is a read-only report, a private API action, or event-triggered work, start with Use Cases instead. This page intentionally follows one repo setup from Agent identity to Activity record.

You need	A workspace where you can connect GitHub, create an Agent identity, and grant capabilities.
Pick one repo	Use a low-risk repo for the first run, such as `acme/api`, and choose a review branch prefix such as `agent/*`.
Choose the agent	Use the external MCP client or hosted session you actually want to evaluate. Do not start by comparing every possible agent surface.
Know what to check	By the end, confirm four things: the agent receives one scoped identity, risky PR API calls pause, Activity shows the exact call path, and the old token stops working after cleanup.
Decide the risky action	For the first run, treat PR creation or update as the approval point. Keep merge absent unless you intentionally test merge approval.

Set Up Access

1. Connect GitHub	Open GitHub, prefer the GitHub App connection, and confirm the target repo is visible.
2. Create the identity	Open Agent identities, create a label such as `Codex repo review`, and set a short expiry.
3. Grant repo access	Grant GitHub remote access for the one repo and allow pushes only to review branches such as `agent/*`.
4. Gate PR actions	Put PR create/update/review/comment actions in Ask mode so the exact payload pauses before execution.
5. Leave merge separate	Do not grant merge for the first run. Add github:pull_requests.merge later only when you intentionally test merge approval.
6. Configure the client	Copy the bearer token into Claude, Codex, Cursor, or another MCP client. Keep the token out of prompts and commit history.
7. Snapshot the setup	Before the run, inspect the identity details and confirm the active grant count, expiry, and client setup values match the task.

Run and Review

Ask for a small change	Ask the agent to inspect the repo, patch in a sandbox, run tests, push `agent/<task-name>`, and open or update a PR with the diff and test result.
Check the branch boundary	The branch push should work only for the allowed review branch pattern. Pushes to `main`, `master`, or another unapproved branch should fail.
Approve the PR action	When the agent asks to create or update the PR, review the owner/repo, base branch, head branch, title, body, diff summary, and test output before approving.
Use GitHub for review	Review the branch or PR with the normal diff, checks, comments, and review history. Merge should remain unavailable unless you granted it separately.
Check Activity before widening scope	Open the identity or Activity view and confirm the record names the caller, capability, repo, branch, approval decision, provider result, and timestamp.

Verify Cleanup

Before granting broader authority, regenerate the Agent identity token once, disable or revoke the test identity, retry the old token, and confirm future tool calls fail. Revocation stops future calls through ExecWarden; it does not undo provider actions that already happened.

Regenerate	The newly issued token works; the previously copied token should fail on the next MCP request.
Disable or revoke	The identity should disappear from the callable surface or return an authorization failure when the same client retries.
Inspect the record	Activity should show the useful calls and approval decision. The identity detail/status and old-token retry explain why later calls are denied.

Expected Result

The agent can read and patch	It can clone/fetch the allowed repo, edit in a sandbox, run tests, and push only to the allowed review branch.
Risky GitHub API actions pause	PR create/update/review/comment actions in Ask mode pause with the exact payload before execution.
Merge is not ambient authority	Merge does not work unless you explicitly grant github:pull_requests.merge, preferably in Ask mode for a reviewed run.
Activity explains what happened	Inspect the caller, capability grant, repo, branch, PR action, approval decision, and provider result before widening scope.
Cleanup is observable	A regenerated, disabled, expired, or revoked identity leaves you with a concrete old-token failure rather than a vague promise that access was removed.