Configuring a repository for coding agents: what the guidance actually says

git - 2026-09-27

This repo is mostly written with a coding agent (Claude Code, running in a cloud session). The agent opens branches and PRs and fixes CI. After a few rounds of that I wondered whether there's any agreed guidance on how the repository should be set up for it: branch protection, CI, instructions files. The answer: yes, but it's spread across vendors, and Simon Willison's guide, which I expected to cover it, mostly doesn't.

Simon Willison: git is the safety net, not the gate

Simon's Agentic Engineering Patterns is about how you work with an agent, not how you configure the repo. The relevant chapter, Using Git with coding agents, treats git as the thing that makes mistakes cheap:

• Keep the agent's changes on branches.
• Start a session by having the agent read git log.
• Let the agent resolve conflicts, dig through reflog, and run bisect.
• Rewriting history on your own branches is fine. He treats history as "a deliberately authored story".

The other relevant chapter is First run the tests: give the agent a fast check it can run itself. Here that's make check.

GitHub: agents don't push to main, and don't merge

GitHub's docs for its own cloud agent read as general guidance for any agent: Building guardrails and Risks and mitigations.

• The agent can't push to the default branch or merge PRs. Humans merge.
• Protect the files that steer the agent (AGENTS.md, CLAUDE.md, MCP config) with CODEOWNERS plus "Require review from Code Owners".
• Keep the workflow token's permissions minimal, and require approval before workflows run on agent-opened PRs.
• If a ruleset blocks the agent, add the agent as a bypass actor instead of weakening the rule for humans.

Anthropic: when the agent runs inside your CI

The claude-code-action security guide covers a different case: an agent triggered by @claude comments inside GitHub Actions.

• Only people with write access can trigger it.
• Never check out an untrusted PR head into the workspace before the agent runs.
• Keep API keys in secrets.
• Keep full output off on public repos: it can leak file contents into public logs.

GitLab: prompt injection and identity

GitLab's security threats in agentic systems page frames things around prompt injection, a dedicated service identity for the agent, and sandboxing. Its external agents page warns that third-party agents like Claude Code don't get GitLab's built-in prompt scanning or network isolation.

What that meant for this repo

Already covered:

• Work goes through branches and PRs.
• CLAUDE.md holds the conventions.
• A security workflow runs gitleaks, actionlint and zizmor.
• Actions are pinned by SHA, and the workflow token's permissions are minimal.

The gaps the guidance exposed, and what I did about each:

• Commit authorship: the cloud session's git identity is Claude <noreply@anthropic.com>. My convention is that I'm the author and Claude is a Co-Authored-By. Fixing that after the fact means rewriting history and force-pushing. So CLAUDE.md now tells the agent to check git config user.email and set my identity before its first commit.
• Merging: CLAUDE.md now says the agent opens PRs but only merges when explicitly asked. It also says which merge method each kind of PR needs: a fork sync must keep its merge commit (see sync-a-diverged-fork-without-its-content.md).
• Branch protection: the minimum is a ruleset on main that blocks force pushes and deletion. That one can't break anything. "Require a pull request" and "require status checks" would, because the publish workflow's README bot commits straight to main, and the built-in workflow token can't be a ruleset bypass actor. "Require linear history" would reject the merge commit a fork sync depends on.
• CODEOWNERS on CLAUDE.md: skipped for now. On a solo repo I can't approve my own PR, so it adds friction without adding review.

Created 2026-09-27T17:01:42+02:00 · Edit