From 67cf34328ce72a76547d74448b9c7801ecb04a12 Mon Sep 17 00:00:00 2001 From: amcheste-ai-agent <278991699+amcheste-ai-agent@users.noreply.github.com> Date: Sat, 25 Apr 2026 09:50:32 -0400 Subject: [PATCH] docs: note Workflows permission and accept-on-installation step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two gotchas discovered while wiring CI for amcheste/overleaf-mcp: - The permissions table didn't list Workflows: Read & Write, but it's required for any push that creates or updates a file under .github/workflows/. GitHub rejects bot pushes that touch workflow files with a clear "refusing to allow a GitHub App ... without 'workflows' permission" message. Adding the entry to the canonical permissions table so future repo setups don't trip over it. - Changing an App's declared permissions is half the work; each existing installation also has to accept the new scope from Settings → Installations → Configure → Review permissions. Without that second click, the installation token issued at runtime still has the old scope and the workflow-push still fails with the same error. Both were learned the hard way today; documenting them so the next person setting up a new repo doesn't have to repeat the discovery. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/design/claude-bot-account.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/design/claude-bot-account.md b/docs/design/claude-bot-account.md index 4b88e35..dc37cb1 100644 --- a/docs/design/claude-bot-account.md +++ b/docs/design/claude-bot-account.md @@ -169,8 +169,11 @@ A GitHub App is the right auth surface for this — not a personal access token. |---|---|---| | Contents | Read & Write | Push branches | | Pull requests | Read & Write | Create/edit PRs | + | Workflows | Read & Write | Add or modify files under `.github/workflows/`. Without this, GitHub will reject pushes that touch a workflow file with `refusing to allow a GitHub App to create or update workflow ... without 'workflows' permission`. Required for any repo where Claude manages CI/CD config (i.e. all of them, in practice) | | Metadata | Read (mandatory) | Required by GitHub | + > After adding or changing permissions on the App, the existing installation also has to **accept** the new scope: *Settings → Installations → Configure → Review permissions*. The App can declare new permissions all it wants; until the installation acknowledges them, the runtime token still has the old scope. + 7. Account permissions: none needed. 8. "Where can this GitHub App be installed?" → **Only on this account**. 9. Create the App, generate a **private key** (`.pem`), download and store it in **Apple Passwords** (secure note attachment) as `amcheste-ai-agent GitHub App private key`.