From 6d0cb3bba3ae96c05776951b5115dcb1c7fdf18d Mon Sep 17 00:00:00 2001
From: William Turner <w_turner@orange.fr>
Date: Sun, 23 Aug 2026 14:51:13 +0000
Subject: [PATCH] Document branch protection + dedicated bot account so the bot
 can only open PRs, never merge

---
 README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/README.md b/README.md
index 86fe219..dce7000 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,32 @@ docker network create web
 13. **Firewall**: `sudo ufw allow 80/tcp 443/tcp`; once the HTTPS routes above are all
     confirmed working, `sudo ufw delete allow 3000/tcp` and `sudo ufw delete allow 9443/tcp`.
 
+14. **Branch protection on `main`**, on every repo you want the bot working on (so it's
+    structurally limited to opening PRs, never merging or pushing directly) — via the repo's
+    Settings → Branches → Add Rule, or the API:
+    ```bash
+    curl -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
+      "$GITEA_URL/api/v1/repos/<owner>/<repo>/branch_protections" \
+      -d '{
+        "rule_name": "main",
+        "enable_push": false,
+        "enable_merge_whitelist": true,
+        "merge_whitelist_usernames": ["<your-human-username>"]
+      }'
+    ```
+    This blocks *all* direct pushes to `main` (everyone goes through a PR) and restricts
+    merging to the human usernames listed — `claude-bot` (see below) is never in that list,
+    so it structurally cannot merge, only open PRs, regardless of what its token can do.
+
+15. **Dedicated bot account** (recommended over using your own account/token for the
+    agent): create a separate Gitea user (e.g. `claude-bot`) via Site Administration → User
+    Accounts, generate its own token (scopes: repository, issue, package — no `admin`,
+    `organization`, or `user` needed), add it as a repo Collaborator with **Write**
+    permission on each automated repo, then use its token as `GITEA_TOKEN` (agent) and
+    `REGISTRY_TOKEN` (CI secret) instead of your own. This makes every PR comment, branch,
+    and PR clearly attributed to the bot instead of you, and its access is easy to revoke
+    independently.
+
 ## Smoke test
 
 - Open a throwaway PR on a repo with the PR webhook set → expect a Claude review comment.