Skip to content

docs(compass): design multi-installation forge credentials (RIG-5653) - #46

Merged
mattwilkinsonn merged 5 commits into
mainfrom
forge/rig-5653-multi-install-design
Oct 19, 2026
Merged

mattwilkinsonn merged 5 commits into
mainfrom
forge/rig-5653-multi-install-design

Conversation

@rigel-mintaka

@rigel-mintaka rigel-mintaka commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Design record for slice 2 of RIG-5653: one compass agent holding repositories under several GitHub App installations. Matt's RIG-5672 rulings are folded in (OQ-1 b, OQ-2 c, OQ-3 every installation, OQ-4 cut over, OQ-5 b).

  • DL-562: the broker mints one token per repository owner, with the owner-grants fallback applied per owner group.
  • DL-563: per-owner token files plus a static compass-forge-credential helper for git (useHttpPath) and jj-vine (tokenCommand).
  • DL-564: every GitHub forge call routes by repository owner: author and reviewer legs, board ingestion and the notify lane.
  • DL-582: a new forge_edit_issue tool edits issue title and body.

Verification

  • bun run gate: design-ledger-gate OK (478 decision files).
  • bun run ref-gate: clean.
  • rumdl check on the record and DL files: no issues.
  • A design-critic pass and review rounds 1-5 ran; findings are folded in.

Risks

T5 and T6 route the reviewer App and the board and notify lanes by owner, so every owner needs the reviewer App installed when one is configured. The grant check enforces this with a named FAILED_PRECONDITION.

Compatibility

Docs only. Slice 1 (single owner per agent) shipped separately. The implementation cuts over the server and runners together on dev.

Documentation

New record docs/designs/compass/server/multi-installation-forge-credentials.md and DL-562, DL-563, DL-564, DL-582. Follow-up: RIG-5819 (gh wrapper).

Refs RIG-5653, RIG-5672

@linear-code

linear-code Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

RIG-5653

RIG-5672

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

Rigel public design docs preview: https://forge-rig-5653-multi-install.docs-2ui.pages.dev

Deployed from forge/rig-5653-multi-install-design at 50ebe07.

@rigel-mintaka

Copy link
Copy Markdown
Contributor Author

Review result: ed23671

Open high: 0. Open medium: 0.

  • A design-critic pass found 9 findings: folded in, or raised as OQ-4 and OQ-5.
  • Round 1 found wildcard tokens leaking to non-default owners (medium) and the DL-564 mapping wording (low); both fixed in a6aaf8c.
  • Round 2 found a stale wildcard-on-the-wire claim (medium); fixed in ed23671.
  • Round 3: no findings.
  • CI: check and deploy succeeded. Mergeable.

This PR stays draft until Matt rules the five open questions in RIG-5672.

rigel-mintaka and others added 3 commits October 18, 2026 10:41
Per-owner broker mint (DL-562), per-owner token delivery to git and
jj-vine through compass-forge-credential (DL-563), and owner-routed
forge write clients (DL-564). Five open questions go to Matt.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
…ant (RIG-5653)

The default-owner marker always names a login, so the wildcard token
reaches only the default installation. DL-564 states the missing-
installation mapping.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
…wire (RIG-5653)

Co-authored-by: Matt Wilkinson <matt@rigel.build>
@rigel-mintaka
rigel-mintaka force-pushed the forge/rig-5653-multi-install-design branch from ed23671 to 1360aa1 Compare October 18, 2026 14:42
rigel-mintaka and others added 2 commits October 18, 2026 17:08
…design (RIG-5653)

Matt ruled OQ-1 b, OQ-2 c, OQ-3 all installs, OQ-4 cut over, OQ-5 b.
Open Questions become Resolved decisions. Board, notify and the reviewer
leg now route by owner (DL-564), forge_edit_issue is added (DL-582), and
the gh wrapper is RIG-5819. DL-562..564 move to Active (Matt).

Co-authored-by: Matt Wilkinson <matt@rigel.build>
…g (RIG-5653)

Review round 4: the author leg reuses the router from buildBoardWebhookWiring,
so author, board and notify calls share one rate gate per installation.
installationErrorCode covers the shared cases; each caller maps
ErrNoInstallation and ErrBudgetExhausted to its own code.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
@rigel-mintaka

Copy link
Copy Markdown
Contributor Author

Review rounds 4-5 at 50ebe07d8cd6ed70ee7bd36140f0bf695be677bf (RIG-5672 rulings folded in): round 4 found 2 medium, both fixed in 50ebe07; round 5 found none. Open high 0, medium 0.

@rigel-mintaka
rigel-mintaka marked this pull request as ready for review October 18, 2026 21:38
@mattwilkinsonn
mattwilkinsonn merged commit 0f97142 into main Oct 19, 2026
2 checks passed
@mattwilkinsonn
mattwilkinsonn deleted the forge/rig-5653-multi-install-design branch October 19, 2026 00:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants