Skip to content

docs(org): explicit bot-PR flow + unset-GH_TOKEN gotcha #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxwellsantoro merged 1 commit into from
Jun 25, 2026
Merged

docs(org): explicit bot-PR flow + unset-GH_TOKEN gotcha #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,11 @@ The branch rule requires the **`merge-gate`** check, which is path-scoped:
- **Docs/org-only PRs** (no `.rs`/`Cargo`/`idl`/`rust-toolchain`) — the heavy `foundry` job is **skipped**; the PR merges on `org-governance` + `merge-gate` in seconds.
- **OS-code PRs** — `foundry` **runs** and `merge-gate` refuses to pass unless it succeeds. OS-code changes are forced through the full Foundry suite.

All PRs are opened by the `ramen-implementer` bot (A2) and approved + merged by a human (A3); see `docs/org/RAMEN_IMPLEMENTER_BOT.md`.
### PR flow: open as the bot, approve as a different identity
Every PR is opened by the `ramen-implementer` bot (A2) and approved + merged by a **different** identity (A3) — GitHub blocks self-approval, which enforces the separation of duties.
- **Open (as the bot):** `export GH_TOKEN=$(python3 tools/org/mint_app_token.py --app-id 4129163 --key ~/.config/ramenos/ramen-implementer.private-key.pem)` → `git push -u origin <branch>` → `gh pr create …`. The PR author is `ramen-implementer[bot]`.
- **Approve + merge (as a different identity):** **`unset GH_TOKEN` first** — otherwise the approve runs as the bot and GitHub rejects the self-approval — then `gh pr review <N> --approve` + `gh pr merge <N> --squash --delete-branch` as the human (A3). (Stage 2: a second bot, `ramen-reviewer`, approves as A3.)
- Full details — identity, key, token mint, bot verification, separation of duties: see `docs/org/RAMEN_IMPLEMENTER_BOT.md`.

## IDL workflow
1. Define the interface in `idl/harness/*.toml` (harness) or `idl/portals/*.toml` (portal).
Expand Down
18 changes: 13 additions & 5 deletions docs/org/RAMEN_IMPLEMENTER_BOT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,14 +90,22 @@ The PR is authored by `ramen-implementer[bot]`. Confirm:
gh pr view <N> --json author --jq .author.login # → app/ramen-implementer
```

## Approving + merging (the human, A3)
## Approving + merging (a different identity, A3)

GitHub forbids a PR author from approving their own PR, so the bot-opened PR
**requires** a different identity to approve — i.e. the human:
GitHub forbids a PR author from approving their own PR, so a bot-opened PR
**requires a different identity** to approve — today the human, later a second
bot (see Stage 2).

> **Critical gotcha — drop the bot token before approving.** `gh pr create` runs
> as the bot because `GH_TOKEN` holds the bot token. The next `gh pr review
> --approve` will *also* run as the bot unless you clear the token first, and
> GitHub rejects it: *"Review cannot approve your own pull request."* **Always
> `unset GH_TOKEN` (or switch to a different credential) between opening and
> approving.**

```sh
unset GH_TOKEN # back to maxwellsantoro (reviewer/A3)
gh pr review <N> --approve --body "..."
unset GH_TOKEN # REQUIRED: drop the bot token first
gh pr review <N> --approve --body "..." # now runs as the human (A3)
gh pr merge <N> --squash --delete-branch
```

Expand Down
Loading