Skip to content
4 changes: 4 additions & 0 deletions docs/ADRs/0033-per-repo-installation-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ Use one GitHub App for triage, code, review, and fix roles to simplify per-repo

**Rejected**: GitHub suppresses events triggered by pushes made with any `GITHUB_TOKEN` or GitHub App installation token, to prevent infinite loops. Two separate Apps work because a push made with App-A's token _does_ generate events that trigger workflows authenticated as App-B. The fix→review loop requires the coder/fix agent to push commits that trigger review — if both roles share one App, the push token matches the workflow's App and the event is silently suppressed, breaking the feedback cycle. At minimum, coder and review must be separate Apps.

> **Note (2026-09):** The first sentence overstates the suppression scope. GitHub's event suppression applies only to `GITHUB_TOKEN` pushes; GitHub App installation token pushes _do_ trigger new workflow runs regardless of App identity — the observed [scaffold-sync dispatch recursion](../contributing/bot-identities.md#app-token-push-recursion) confirms this. The separate-Apps conclusion still holds for permission isolation ([ADR 0007](0007-per-role-github-apps.md)), but the suppression-based rationale above was incorrect. See also [`platform-nativeness.md`](../problems/platform-nativeness.md), which notes this overstatement.

### Alternative 3: Per-repo as a separate codebase

Build a standalone per-repo tool or action that does not share infrastructure with per-org fullsend.
Expand Down Expand Up @@ -335,6 +337,8 @@ Ordered by the project's threat priority (external injection > insider > drift >
- **`event_payload` size**: Per-org's `dispatch.yml` builds a minimal payload from `$GITHUB_EVENT_PATH` (extracting only `issue`, `pull_request`, and `comment` fields), avoiding the 65KB `workflow_call` input limit. Per-repo's shim forwards `event_action` via `workflow_call` and `reusable-dispatch.yml` reads remaining context from `github.event.*` expressions, following the same pattern. Large PR event payloads are unlikely to be an issue since the shim does not pass the full payload as an input.
- **App identity confusion**: Users unfamiliar with the fix→review loop requirement may attempt a single-App setup and get silent failures (no review triggered after fix pushes).

> **Note (2026-09):** The "silent failures" failure mode described above is incorrect. GitHub's event suppression applies only to `GITHUB_TOKEN` pushes; App installation token pushes _do_ trigger new workflow runs regardless of App identity (see [correction note in Alternative 2](#alternative-2-single-github-app-for-all-roles)). A single-App fix push would therefore trigger the review workflow. The actual risk of a single-App setup is that it grants every role the union of all permissions — violating least-privilege ([ADR 0007](0007-per-role-github-apps.md)) — and that GitHub's `422 Can not approve your own pull request` error blocks one identity from both authoring and approving a PR.

### Mitigations

- **CODEOWNERS on workflow and config**: `fullsend admin install` should add CODEOWNERS entries protecting `.github/workflows/fullsend.yml` and `.fullsend/` so that changes to the workflow trigger, agent config, and sandbox policies require approval from designated owners. This is the primary defense against both workflow misconfiguration and insider modification of agent behavior. In per-org mode, the `.fullsend` config repo has its own CODEOWNERS; per-repo must replicate this governance at the file level.
Expand Down
31 changes: 28 additions & 3 deletions docs/contributing/bot-identities.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,36 @@ Fullsend agents authenticate as GitHub Apps; the table below also includes non-a
| retro | `fullsend-ai-retro[bot]` | Files retro issues, posts PR comments |
| prioritize | `fullsend-ai-prioritize[bot]` | Prioritizes issues |
| renovate | `renovate-fullsend[bot]` | Dependency updates (not a fullsend agent) |
| sync | `fullsend-ai-sync[bot]` | Converges scaffold files and per-repo variables across `.fullsend`'s `repos.yaml` targets; commits directly to `main` |

When referencing bot identities in code (e.g., trusted actor lists, dispatch filters), always verify the login name against this table. Do not assume each agent role has a unique app identity — the fix agent reuses `fullsend-ai-coder[bot]`, not a separate `fullsend-ai-fix[bot]`.

**Shared vendor identity:** The default deployment model uses a shared, vendor-owned App (per ADR 0029/0059/0068). For adopting orgs other than `fullsend-ai`, the review bot's login is `fullsend-ai-review[bot]`, not `${ORG_NAME}-review[bot]`. Any code that gates on the review bot's identity must match **both** the org-specific form (`${ORG_NAME}-review[bot]`) and the shared vendor form (`fullsend-ai-review[bot]`). See #5550 for the bug this caused.
## Scaffold-sync write path

**REST vs. GraphQL login format:** the `[bot]` suffix above is the REST/App-slug form. GitHub's GraphQL API omits it — a bot author's `login` field comes back as `fullsend-ai-coder`, not `fullsend-ai-coder[bot]`, with `__typename: "Bot"`. Comparing a GraphQL-sourced login against a literal `"...[bot]"` string never matches (see #5575) — match on `__typename == "Bot"` plus the un-suffixed login instead.
The `fullsend-ai-sync[bot]` App has a broader write path than the agent Apps listed above. Three properties are load-bearing and must be considered when building trusted-actor lists, dispatch filters, or security assessments:

**`gh pr view --json` format:** the `gh pr view --json author` CLI command uses a different schema than raw GraphQL — it exposes `.author.is_bot` (boolean) and `.author.login` (with an `app/` prefix, e.g. `app/fullsend-ai-coder`), but does **not** expose `__typename`. When using `gh pr view --json`, check `.author.is_bot == true` plus `.author.login` against the `app/`-prefixed name (see #5536).
### Ruleset bypass
Comment thread
ggallen marked this conversation as resolved.
Resolved

The sync App holds `bypass_mode: always` on the `fullsend-ai/fullsend` `main` ruleset. Its commits are direct pushes to `main` — no PR, no review, no status checks. This is intentional: scaffold convergence is a cross-repo reconciliation that runs unattended after every push to `main`.

### Workflow-write scope

The sync App has workflow-write permission. Combined with the ruleset bypass, `.github/workflows/` on `main` is writable by the sync path with no human in the loop. This is distinct from the coder token path: the `coder` token has no `workflows` permission (`internal/mintcore/github.go`), so code agents cannot push workflow files (see #6512). The sync App can. Both facts are correct — read in isolation, the #6512 statement about the coder token is easy to take as covering every bot, but it applies only to the coder token, not the sync path.

### App-token push recursion

GitHub's "events triggered by `GITHUB_TOKEN` will not create a new workflow run" suppression is scoped to `GITHUB_TOKEN` and does not apply to GitHub App installation tokens. A sync commit to `main` therefore re-triggers `notify-scaffold-sync`, which dispatches again. Observed 2026-08-24: merge `cfdbf2ff` at 14:29 → dispatch → sync commit 14:51 → dispatch → sync commit 14:52 → dispatch → stop. Each scaffold-touching merge costs ≥2 dispatch rounds. This is by design — the second round converges any files that depend on the first sync — but it interacts with the convergence non-idempotence tracked in #6553. See also [CI Workflows § Scaffold-sync dispatch recursion](ci-workflows.md#scaffold-sync-dispatch-recursion).

## General identity notes

### Shared vendor identity

The default deployment model uses a shared, vendor-owned App (per ADR 0029/0059/0068). For adopting orgs other than `fullsend-ai`, the review bot's login is `fullsend-ai-review[bot]`, not `${ORG_NAME}-review[bot]`. Any code that gates on the review bot's identity must match **both** the org-specific form (`${ORG_NAME}-review[bot]`) and the shared vendor form (`fullsend-ai-review[bot]`). See #5550 for the bug this caused.

### REST vs. GraphQL login format

The `[bot]` suffix above is the REST/App-slug form. GitHub's GraphQL API omits it — a bot author's `login` field comes back as `fullsend-ai-coder`, not `fullsend-ai-coder[bot]`, with `__typename: "Bot"`. Comparing a GraphQL-sourced login against a literal `"...[bot]"` string never matches (see #5575) — match on `__typename == "Bot"` plus the un-suffixed login instead.

### `gh pr view --json` format

The `gh pr view --json author` CLI command uses a different schema than raw GraphQL — it exposes `.author.is_bot` (boolean) and `.author.login` (with an `app/` prefix, e.g. `app/fullsend-ai-coder`), but does **not** expose `__typename`. When using `gh pr view --json`, check `.author.is_bot == true` plus `.author.login` against the `app/`-prefixed name (see #5536).
8 changes: 8 additions & 0 deletions docs/contributing/ci-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,14 @@ Redaction covers:

**Residual limitations:** content scanning cannot catch every encoding or obfuscation of a secret in a text-classified file (base64, hex, split tokens). Same-job PR-head code could theoretically race the upload step after redaction; isolating redaction in a separate job would narrow that window further.

## Scaffold-sync dispatch recursion

`notify-scaffold-sync` fires on every `push` to `main`. Its job generates a GitHub App installation token for `fullsend-ai-sync[bot]` and dispatches `fullsend-updated` to `fullsend-ai/.fullsend`, which runs `sync-scaffold` to converge per-repo variables and scaffold files.

Because the sync App authenticates with an App installation token (not `GITHUB_TOKEN`), GitHub's workflow-suppression rule does not apply — a sync commit pushed to `main` re-triggers `notify-scaffold-sync`, which dispatches again. Each scaffold-touching merge therefore costs ≥2 dispatch rounds: the first sync converges files, the second re-enters and converges any state that depends on the first sync's output. The chain terminates when a sync round produces no diff.

This recursion is by design but interacts with the convergence non-idempotence tracked in #6553. See also [Bot Identities § App-token push recursion](bot-identities.md#app-token-push-recursion) for the observed dispatch chain and the security-relevant distinction between the coder token (no `workflows` permission) and the sync App (has `workflows` permission plus `bypass_mode: always` on the `main` ruleset).

## Additional conventions

- Always include the workflow file itself in its own `paths:` filter so changes to the workflow trigger its own CI.
Expand Down
2 changes: 1 addition & 1 deletion docs/problems/platform-nativeness.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ gh-aw uses GitHub's own `GITHUB_TOKEN`, scoped per-job. The agent gets a read-on

**A real gap for implicit dispatch — but not a fatal one.** GitHub's own [`GITHUB_TOKEN` documentation](https://docs.github.com/en/actions/concepts/security/github_token) states the general rule: events triggered by `GITHUB_TOKEN` do not create a new workflow run, with `workflow_dispatch` and `repository_dispatch` as the only exceptions. `pull_request` events (`opened`/`synchronize`/`reopened`) get a narrow carve-out — they still fire, but land in an **approval-required** state a human must manually release. Every other `pull_request` activity type, plus issues and label events, get no carve-out at all: an issue opened or a label applied via `GITHUB_TOKEN` silently does not trigger the next workflow.

That breaks a pipeline that hands off purely through *implicit* GitHub-native events — retro filing a follow-up issue, triage applying `ready-to-implement`, code opening a PR for review to pick up automatically. But `workflow_dispatch` and `repository_dispatch` are exempt from this suppression regardless of which token performs them, so a stage can sidestep the whole problem by explicitly calling `gh workflow run <next-stage>` as its own last step, using nothing more than `actions: write`. A pending fullsend proposal ([PR #5649](https://github.com/fullsend-ai/fullsend/pull/5649), not yet merged) documents exactly this pattern — an identity-light "Lite Auth Mode" built around explicit `workflow_dispatch` handoffs — and separately clarifies that a shared App's pushes and labels were never actually broken by this suppression rule; only the built-in `GITHUB_TOKEN` is affected, and [ADR 0033](../ADRs/0033-per-repo-installation-mode.md)'s original text overstated that constraint.
That breaks a pipeline that hands off purely through *implicit* GitHub-native events — retro filing a follow-up issue, triage applying `ready-to-implement`, code opening a PR for review to pick up automatically. But `workflow_dispatch` and `repository_dispatch` are exempt from this suppression regardless of which token performs them, so a stage can sidestep the whole problem by explicitly calling `gh workflow run <next-stage>` as its own last step, using nothing more than `actions: write`. A pending fullsend proposal ([PR #5649](https://github.com/fullsend-ai/fullsend/pull/5649), not yet merged) documents exactly this pattern — an identity-light "Lite Auth Mode" built around explicit `workflow_dispatch` handoffs — and separately clarifies that a shared App's pushes and labels were never actually broken by this suppression rule; only the built-in `GITHUB_TOKEN` is affected, and [ADR 0033](../ADRs/0033-per-repo-installation-mode.md)'s original text overstated that constraint (ADR 0033 now contains its own [correction note](../ADRs/0033-per-repo-installation-mode.md#alternative-2-single-github-app-for-all-roles) documenting this).

That weakens retriggering as its own justification for per-role Apps: it's solvable with an explicit dispatch call, not a different bot identity. What real identity separation still buys is (a) least-privilege blast-radius separation (ADR 0007's original argument) and (b) working around GitHub's `422 Can not approve your own pull request` error, which blocks one identity from both authoring and approving a PR regardless of token type — a narrower but real reason a review-stage identity must differ from the code-authoring identity once auto-merge is in play. gh-aw's [FAQ](https://github.github.com/gh-aw/reference/faq/) documents an operator-supplied `GH_AW_CI_TRIGGER_TOKEN` PAT as its own workaround for the same suppression, but doesn't appear to document the zero-privilege explicit-`workflow_dispatch` escape hatch as an alternative — that may be a simpler option available to gh-aw workflows too, not something inherent to fullsend's approach.

Expand Down
Loading