How do I run a coding agent on my GitHub repo without merging unreviewed code?

I do not let a coding agent merge. I let it open a pull request on a branch it created, in a sandbox I did not give production secrets. I read the diff before Actions even run.

Teams skip that split. They paste a bot token with write access to main, or they turn off required reviews so the agent can finish, and they call it autonomy. I call it an unreviewed merge with extra steps.

The question I get from operators who already use chat in the editor is this one: how do I put a coding agent on my GitHub repo without merging unreviewed code? If you still need the definition, start with what a coding agent is. This page assumes you already know it is a loop with tools, not a chat window.

A coding agent belongs on a branch, in a sandbox, behind a review. Assigning a GitHub issue always opens a pull request, and a prompt can stay on a branch until you create one. Either way it runs in a GitHub Actions VM, a person with write access inspects the diff and starts Actions, and the model never merges.

Put the agent on a branch, not on main

Main stays a human grant. The agent may clone, edit, test, and open a pull request on a branch it created. Branch protection, required reviews, and Actions approval sit outside the model, and if those gates are off you gave the agent the keys.

I treat a coding agent the way I treat a new contractor with a laptop. They get a clone, a ticket, and a way to open a pull request. They do not get admin on the default branch, the production deploy key, or the right to approve their own work.

Anthropic’s Building effective agents (19 December 2024) draws the line I still use. A workflow is a predetermined path. An agent is a model that directs its own tool use.

On a repository that distinction is practical. A GitHub Action that runs a linter is a workflow. A model that chooses files, edits them, runs tests, and opens a pull request is an agent.

The appendix of that same Anthropic note is blunt about code. Automated tests help verify function. Human review remains crucial for whether the change belongs in the system.

NIST’s AI RMF 1.0 (January 2023) names four functions: Govern, Map, Measure, Manage. On a repo that means who may assign and merge, which jobs the agent may touch, whether the pull request meets the finish line, and the review plus the Actions kill switch.

The finish line is a pull request, not a merge. Opening a branch is not shipping, and green CI on an unreviewed diff is not shipping either.

Checks run the tests you already have. They do not read whether the agent rewrote a workflow file to print a secret. That is why GitHub, OpenAI, and Anthropic all put a human between the agent and the default branch.

How Copilot coding agent is built to stay off main

GitHub Copilot coding agent, which GitHub’s Copilot docs (2026) also call Copilot cloud agent, runs in an Actions sandbox. It pushes only to a copilot/ branch. Workflows wait for a human, and the person who assigned the issue cannot supply the required approval.

GitHub’s 19 May 2025 Copilot coding agent announcement is the product in one sentence. Assign a task or issue to Copilot. It runs in the background with GitHub Actions and submits its work as a pull request.

GitHub’s “Assigning tasks to Copilot cloud agent” docs (2026) still describe assignment the same way: pick Copilot as the assignee, optional prompt, base branch, model.

YouTube

Open original

GitHub walked how Copilot coding agent stays off main on 30 May 2025.

Assigning an issue always creates a pull request. Starting from a prompt can stay on a branch first, which is useful when you want to steer before anyone else sees a PR. Either path, the agent works in an ephemeral GitHub Actions environment where it can explore the code, edit, and run tests.

GitHub’s Copilot coding agent risks and mitigations page (2026) lists the controls I actually depend on. Only users with write access can trigger the agent. Comments from people without write access are never presented to it.

The agent can push to a single branch: a new copilot/ branch for a fresh task, or the existing pull request branch if you mention @copilot there. It cannot push to main. It cannot run git push itself, and credentials are limited to simple push operations.

Draft pull requests must be reviewed and merged by a human. Copilot cannot mark its own pull request as ready for review, cannot approve it, and cannot merge it.

Actions is the other gate. By default GitHub treats the agent like an outside collaborator on an open source project, so workflows do not run when Copilot pushes.

GitHub is explicit about why. Actions can be privileged and can see secrets. You inspect the proposed changes, especially anything under .github/workflows, then you click Approve and run workflows.

On 13 March 2026 GitHub added a repository setting so administrators can skip that human approval and let workflows run immediately. Default remains require a human. I leave the default on, because a rewritten workflow that uses your secrets only runs if you start it.

Required reviews are the third gate. GitHub’s “Reviewing a pull request created by Copilot” docs (2026) are unambiguous. If the repository requires pull request approvals, your approval of a Copilot pull request you initiated does not count.

Someone else must approve. That is how you stop one person from assigning Copilot and merging their own unreviewed code under a green check.

• Write access to assign. No write access, no task, and no comment reaches the agent.
• Push only to a copilot/ branch or to the PR branch you mentioned @copilot on. Never to main.
• Firewall on the internet. Blocked destinations show up on the pull request.
• Actions wait for Approve and run workflows unless an admin turned that off.
• Independent review. The assigner cannot satisfy required approvals.
• Signed commits, co-authored by the person who assigned the issue, with a link to the session log.

There are limits I plan around. GitHub’s Copilot cloud agent docs (2026) cap a session at 59 minutes, and the agent works in one GitHub-hosted repository and opens one pull request per task. Some branch rulesets that restrict commit authors will block it unless you add Copilot as a bypass actor.

I still write the issue as if a careful junior will read it: scope the files, name the test that must pass, and name the files it should not touch. Copilot can take custom instructions and MCP servers, with GitHub and Playwright on by default, so keep the extra tools to the job the same way I keep a short list in AI agent tool calling.

Give the repo a map the agent can read

AGENTS.md is a map of roughly a hundred lines, and the rest of the knowledge lives in docs you keep true. The Codex harness reads that map, then uses tools inside a sandbox and asks for approval when the host says so. A novel in the prompt is not a map.

OpenAI’s Codex docs (2026) are plain. Codex reads AGENTS.md files before doing any work. It builds an instruction chain once per run.

Global guidance lives under ~/.codex. Then it walks from the project root down to the working directory, taking at most one file per folder, AGENTS.override.md before AGENTS.md. Later files override earlier ones, and the combined size stops at project_doc_max_bytes, 32 KiB by default.

OpenAI’s Harness Engineering note (11 February 2026) is the lesson I actually use. They tried one giant AGENTS.md. It failed.

Context is scarce, so a manual crowds out the task. Too much guidance becomes non-guidance, the file rots, and you cannot lint a blob. They treat AGENTS.md as a table of contents of roughly 100 lines, and they treat a structured docs/ directory as the system of record.

Pointers, not essays: the agent starts with a small entry point and is taught where to look next. I do not paste the style guide or the schema. I link them.

• How to install, and which package manager.
• The exact test command and the lint command.
• Where the architecture note lives.
• Which directories are off limits, including .github/workflows unless the issue says otherwise.
• How to open a pull request.

Nested folders can carry an override when payments is not the same shop as search. OpenAI’s own example is a payments AGENTS.override.md that swaps the test command and forbids rotating keys without the security channel.

The harness is the other half. OpenAI’s Codex as a platform note (19 August 2026) says the reusable part is the agent loop: understand the task, keep context, call tools, expose progress, handle failures, request human approval, return a result. The open-source Codex harness at github.com/openai/codex is what enforces sandbox and approval policies.

Michael Bolin’s Unrolling the Codex agent loop (23 January 2026) is the same split from the inside: the harness orchestrates the user, the model, and the tools. The model should not own the loop. Kernel is the name I give that runtime on my own stack, Copilot’s runtime is GitHub Actions, and Codex’s runtime is this harness.

OpenAI’s 2026 Codex guide also lets you hang a Code Review Rules section off the same file for Codex review on GitHub. Keep those rules about behavior to flag, and leave formatting to CI. The agent should not be the linter.

Three steps I actually run

Write a map, run the agent off main, then review before Actions and merge. Skip the map and the agent guesses your test command. Skip the sandbox and it can reach the default branch, and skip the review and you merged unreviewed code, whatever the model’s name on the commit.

1. 01

   Write a map the agent can read

   Add a short AGENTS.md at the repo root. Point at install, test, lint, architecture, and the files it must not touch. Turn on branch protection: required reviews, required status checks, no force push to main. If the repo already requires one approval, keep GitHub’s extra approval for unattributed Copilot pull requests on. The map is for the model. The ruleset is for everyone, including the model.

2. 02

   Run the agent in a sandbox off main

   Write an issue with a finish line a script can see: the test name, the files in scope, the files out of scope. Assign Copilot, or start Codex in a worktree, or run the Claude Agent SDK against a clone that cannot push to origin/main. Confirm the agent is on a copilot/ branch or a worktree branch, not on the default branch. Confirm it has no production secrets in that environment.

3. 03

   Review the PR, then approve Actions, then merge

   Read the diff yourself. Watch .github/workflows and lockfiles and auth code. Click Approve and run workflows only after that read. Let CI speak. Ask @copilot to fix what failed, or push onto the branch yourself. A person who did not assign the task supplies the required approval. Then merge. The assigner does not rubber-stamp their own agent.

I run the first two steps once per repository, then I reuse them. The map drifts, so I treat a stale AGENTS.md the way I treat a stale README: it is a bug. The third step is every pull request: a diff, a human, then Actions.

Own the loop when Copilot is the wrong shape

Copilot is the hosted path on GitHub, Codex is the harness you can run locally or in your own product, and the Claude Agent SDK is that loop as a library in Python or TypeScript. Same job: tools, a sandbox, an approval. Pick the host that matches where the code already lives.

Use Copilot coding agent when the work already lives as GitHub issues and you want the sandbox, the copilot/ branch, and the Actions gate without building a runtime. Use Codex when you want the open harness, AGENTS.md as the map, and approval policies you configure in the host. Use the Claude Agent SDK when you need that loop in your own process, with permission modes you set in code.

Anthropic renamed the Claude Code SDK to the Claude Agent SDK on 29 September 2025. The blog is the design in one line: give the agent a computer, the same tools a programmer uses, and a loop of gather context, take action, verify work, repeat.

The 2026 Agent SDK docs match that. You get Read, Write, Edit, Bash, Glob, and Grep, and you do not implement the tool loop. You set which tools exist and which need approval.

Permissions are the repo question in library form, and Anthropic’s 2026 Agent SDK permission docs list the modes I actually pick from. Default mode asks through your `canUseTool` callback. `dontAsk` denies anything you did not pre-approve, which is the locked-down headless agent.

`acceptEdits` auto-approves file edits inside the working directory, and `plan` explores without editing source. `bypassPermissions` auto-approves almost everything. Anthropic’s 2026 Agent SDK permission docs say use that last mode with caution, in a controlled environment.

Pair allowedTools with dontAsk when the agent should only read, or only edit, and must not wander into Bash. Do not set allowedTools to Read and then set bypassPermissions. The docs warn that bypassPermissions still approves the tools you did not list.

I do not point the Claude Agent SDK at my working tree on main with bypassPermissions and a production GitHub token. That is the laptop version of merging unreviewed code. I point it at a worktree, and I give it a token that can push to a feature branch and open a pull request.

I keep deny rules on rm of critical paths, on .env, and on .github/workflows unless the issue is about workflows. Hooks run first in Anthropic’s evaluation order and can still block a call in bypassPermissions. Use a PreToolUse hook if a check must run on every tool, not only the ones that fell through.

Codex as a platform (19 August 2026) makes the same split for product teams. The application owns context, tools, and consent. The harness owns the loop and the sandbox.

Their Relay sample requires human approval before a consequential write. On a repo that write is merge, and on Actions it is the workflow run.

Review the PR as if a stranger wrote it

Read the diff before you start Actions. Watch workflow files, secrets, lockfiles, and auth. Session logs exist so you can see the tools it called, not so you can skip the diff, because a green check on a branch you did not read is still unreviewed code.

GitHub’s “Reviewing a pull request created by Copilot” docs (2026) tell you to check the pull request thoroughly before merging. I do the same for Codex and for anything the Claude Agent SDK opened through the GitHub API.

A bot author raises the bar, because it will copy whatever pattern already exists, including the bad ones.

OpenAI’s February 2026 harness note says that out loud: Codex replicates patterns in the repository, even uneven ones. Your review is where those copies stop.

• Diff first, Actions second. You are looking for workflow edits, new network calls, and copied secrets before CI has a chance to run them.
• Session log. Copilot’s commit message links it. Codex and the Agent SDK should log every tool call the same way Kernel does.
• Tests that the issue named. A new passing test the agent wrote for its own function is not the test you asked for.
• Files out of scope. An issue about a button should not retouch the billing client.
• Lockfiles and new dependencies. GitHub says Copilot checks new dependencies against the Advisory Database. You still read the addition.
• Auth, crypto, migrations, and anything that sends mail or money. If those moved, stop. That is when not to let an agent write code, on purpose.

You can mention @copilot on the pull request to ask for a fix, or you can check out the branch and edit it yourself. I do both. Small test gaps I push myself, and wrong design I send back with a comment that names the file.

GitHub will not count your approval if you were the one who assigned the issue, so get a second person. If you are a solo operator, wait and read it cold. Do not merge in the same sitting you assigned it.

GitHub’s 2026 Copilot coding agent mitigations also run CodeQL, secret scanning, and a malware check on new dependencies before the agent finishes the pull request. Those are extra CI, not the review. They do not know whether the change matches the product, or whether the agent deleted a guardrail because the test was annoying.

Jobs I will not assign

A coding agent is for a scoped change with a test you already trust. It is not for auth, production deploys, or a first pass at a system you cannot yet describe. This page is the how, and the stop list lives in the next guide in the cluster.

I assign work that looks like the backlog GitHub itself describes in 2026: a bug with a failing test, a small feature in a well-tested corner, coverage on a function that already has a shape, docs, a refactor the tests already pin down. The stop list is when not to let an agent write code.

I keep migrations that drop columns, Actions that publish the package, session-handling rewrites, and live incidents off the assignee list. The agent can draft on a branch. A person ships those.

I also do not assign a vague issue. “Improve the dashboard” is a chat prompt. “Add a CSV export on /reports that matches the columns in docs/reports.md, covered by the existing reports.spec.ts cases, without changing auth” is an issue.

If I cannot name the test, I do not have a finish line, and I should not start a loop that writes files. That is the same rule I use for any agent. A coding agent does not get a pass because git makes the work look official.

Prompt injection is not theoretical here. GitHub’s Copilot coding agent risks and mitigations page (2026) says users can hide instructions in issues and comments. GitHub filters hidden characters and HTML comments before the text reaches Copilot.

That is a mitigation, not a guarantee. I do not let random outside commenters steer the agent, which GitHub already blocks by ignoring low-permission comments. I still read the issue I am about to assign, because I can hide a bad instruction from myself as easily as a stranger can.

If the repository has no tests, I do not put a coding agent on it and hope. I write the tests first, or I use the agent only to propose tests on a branch I will read line by line.

An agent that cannot verify its work will keep editing until the session budget dies. Anthropic’s 2025 Agent SDK post puts verify in the loop on purpose. GitHub’s sandbox can run the tests you have, and it cannot invent a specification you refused to write.

Score the artifact, then widen the grant

Score the pull request against the issue, on a frozen set of jobs, before you let the agent take more of the backlog. Pretty traces that miss the test are zeros. Autonomy is a grant you widen after the score holds, not a switch you flip for the whole company.

I keep a short list of issues I already know the answer to. I assign them. I record whether the pull request matched the files, whether tests the issue named stayed green, whether the agent touched workflow files, and whether a person had to rewrite the change.

I do that more than once, because a single lucky branch is not a score. GitHub’s 2026 Copilot usage metrics can show enterprise owners how many Copilot pull requests were created and merged, and median time to merge. That is throughput, not quality, and I will not cite a merge rate I did not measure on this repo.

NIST’s Measure function (January 2023) is the same idea in slower language: pick a method, track risk over time, use feedback. On a coding agent the method is the artifact.

Did the branch exist? Did the named tests pass after a human started Actions? Did an independent reviewer approve, and did anything in .github/workflows change without the issue asking for it?

Log the tool calls. Copilot’s session log, Codex’s session jsonl, the Agent SDK’s streamed messages: that is the trace. If you only keep the final message, you will not see the bad search or the extra dependency.

Kernel, on my side, is the loop those traces sit on: named tools, memory, retries, permissions, the stop rule. I do not need GitHub to call it Kernel. I need the runtime, whoever owns it, to be able to kill a runaway session and to refuse a push to main.

Copilot’s 59-minute cap, Codex’s approval policy, and the Claude Agent SDK’s dontAsk mode are all stop rules. Wire one. Then widen the grant one class of issue at a time: docs first, tests second, small features in a pinned module third, auth last or never.

OpenAI’s February 2026 internal experiment is easy to misread. They reported a product whose code Codex wrote, with humans still prioritizing work, writing acceptance criteria, and validating outcomes, and they were clear that this depended on the structure of that repository. That is not a license to auto-merge Copilot on a brownfield app with a thin test suite.

Until your AGENTS.md, your tests, and your review habit look like that, required review stays on. The destination is a repository where a coding agent can take a scoped issue, open a pull request, and wait. You still merge, and you still own the default branch.