Design: obot GitHub App for agent and automation access

1. Context and goals

The obot portfolio previously ran on a dedicated GitHub machine account (obot-claw) plus an always-on OpenClaw runtime — a second full identity with long-lived credentials to secure and rotate. That setup was wound down in July 2026 (hub archived; see the #7 design), leaving a gap: agents and automation still need a non-personal identity with scoped access to the portfolio repos, so that automated actions are attributable to the automation rather than to @jwildfire personally.

A GitHub App fills the gap with far less surface area than a machine account: tokens are short-lived (1 hour), scoped to an explicit repo whitelist, and minted from a single private key that Jeremy controls. Success criteria (from #3):

• The app is registered under @jwildfire and installed on the whitelisted portfolio repos.
• At least one agent flow and one GitHub Actions flow authenticate through it.
• No obot-claw credentials remain in use.

2. Architecture — one app, two token flows

App registration (@jwildfire)          ── App ID + private key (PEM)
        │
        │  sign RS256 JWT (≤10 min TTL)
        ▼
POST /app/installations/{installation_id}/access_tokens
        │
        ▼
Installation token (1 h TTL, repo-whitelisted, permission-capped)
        │
        ├── local agent:  GH_TOKEN=$(obot-app-token) gh …   /  git push via x-access-token
        └── Actions:      actions/create-github-app-token@v2 → ${{ steps.app.outputs.token }}

Both consumers end at the same place: an installation token whose blast radius is capped three ways — by expiry (1 hour), by the installation's repo whitelist, and by the app's permission set (§3). Actions performed with the token are attributed to the app's bot login (<slug>[bot]), so bot work is visibly distinct from @jwildfire's own.

2.1 Which identity, when

The AGENTS.md attribution convention ("This … was drafted by Claude Code using …") continues to apply to the content of issues, PRs, and comments regardless of which identity posts them.

Bot-attributed git commits use the standard app-bot author format, with the bot user ID looked up once after registration (gh api '/users/<slug>[bot]' --jq .id):

git -c user.name='<slug>[bot]' \
    -c user.email='<ID>+<slug>[bot]@users.noreply.github.com' commit …
git push https://x-access-token:<TOKEN>@github.com/<owner>/<repo>.git

3. App registration specification

3.1 Permissions (D2)

As registered (2026-07-04): App ID 4215246 · installation 144370633 (the five §3 repos) · bot login obotclaw[bot], user ID 299836032 · commit author obotclaw[bot] <299836032+obotclaw[bot]@users.noreply.github.com>.

D2 resolved to this broader set (the draft recommended a minimal one): Workflows (write) and Actions (read) are requested up front so the anticipated follow-on consumers — the @claude PR-responder, which needs its workflow file pushed to each participating repo, and cross-repo automation that watches run status — don't each trigger an edit-and-re-approve round-trip on the installation. The set is still bounded: no administration, organization, or account permissions, and the webhook stays disabled.

Known limitation (verified against the GitHub App permissions reference, 2026-07-03): apps have no permission for user-owned Projects (v2) — the Projects permission exists only at the organization level. The app therefore cannot read the obot Roadmap user Project, and the site's ROADMAP_TOKEN PAT (project read) stays in place for Project-Status reads. The app replaces the obot-claw identity, not that token.

4. Key management (D3)

• Rotation: GitHub Apps allow two active private keys, so rotation is zero-downtime — generate the new key, update Keychain + Actions secrets, delete the old key. Cadence: annually, or immediately on any suspicion of exposure.
• Revocation: deleting the app's keys (or uninstalling the app) kills all future token minting instantly; outstanding installation tokens die within the hour. This is the emergency stop the obot-claw machine account never cleanly had.

5. Agent-side tooling (D4)

Local agents need installation tokens without hand-running the JWT dance. Recommended shape: a small self-contained script plus a thin skill, both in safety.agent (the agent scaffold owns agent tooling; there is no obot.agent repo — that idea is shelved):

• scripts/obot-app-token — ~40 lines of bash on openssl: read the PEM from Keychain, sign a 10-minute RS256 JWT, exchange it for an installation token, print the token. No third-party dependencies (the community gh-token extension was considered and passed over — an extra dependency for something this small, and less auditable).
• A skill (e.g. obot-identity) documenting when to act as the bot (§2.1) and the two usage patterns:

  GH_TOKEN=$(obot-app-token) gh api …        # API / issues / PRs as the bot
  git push https://x-access-token:$(obot-app-token)@github.com/… 

Acceptance for the agent flow: from a normal working session, mint a token and post a comment as the bot on a designated test issue — then confirm the comment renders as <slug>[bot].

6. GitHub Actions integration

Workflows use the first-party actions/create-github-app-token@v2:

- id: app
  uses: actions/create-github-app-token@v2
  with:
    app-id: ${{ secrets.OBOT_APP_ID }}
    private-key: ${{ secrets.OBOT_APP_PRIVATE_KEY }}
    # owner/repositories: defaults to the current repo; widen per workflow as needed
- run: gh issue comment … --repo jwildfire/obot.roadmap
  env:
    GH_TOKEN: ${{ steps.app.outputs.token }}

• First consumer (acceptance test): app-smoke-test.yml in obot.roadmap, workflow_dispatch-only — mints a token and posts a comment on #3 as the bot. Proves the GHA path end-to-end without inventing automation the portfolio doesn't need yet.
• Real consumers, later: the scheduled diary/briefing automation, the @claude PR-responder (claude-code-action authenticated with this app's token via its github_token input, so replies and commits post as obotclaw[bot]) — each its own requirement, deliberately out of scope here; this app is their prerequisite — and any cross-repo rollup that must write outside the workflow's own repo.
• Unchanged: deploy-site.yml keeps the default GITHUB_TOKEN (public reads + Pages deploy) and ROADMAP_TOKEN (user-Project reads, §3.1).

7. obot-claw credential retirement

The requirement closes only when the old identity's credentials are dead, not merely unused:

8. Decisions

All four decisions were resolved by @jwildfire on 2026-07-04 in a working session (recorded on #3). Original recommendations kept for the record; D2 resolved differently than recommended.

9. Out of scope

• Scheduled agentic runs (nightly diary/briefings) — explicitly excluded by the requirement; file a separate Requirement once this app exists and the cadence is decided. This design is its prerequisite.
• The @claude PR-responder loop — long-running task handoff where Jeremy discusses work with the bot via PR comments and claude-code-action responds event-driven from GitHub Actions. Its own follow-on requirement; this app supplies its identity (the action's github_token input accepts a token minted from a custom app). D2's broader permission set anticipates it.
• The shelved obot worker machine / obot.agent repo — the helper lands in safety.agent; nothing here depends on new infrastructure.
• Webhooks and event-driven automation; GitHub Marketplace listing.
• Replacing ROADMAP_TOKEN — impossible today (no user-Projects permission for apps, §3.1).
• Transferring app ownership to an organization — possible later without re-registration if the portfolio ever moves back into an org.

10. Task preview

To be filed as Tasks on #3 after design sign-off; listed here to show the intended decomposition.

1. Register the app per §3 and generate a private key — @jwildfire, guided (interactive GitHub login required); install on the five whitelisted repos. (depends on D1/D2)
2. Store credentials: PEM → Keychain; OBOT_APP_ID / OBOT_APP_PRIVATE_KEY secrets → obot.roadmap. (D3)
3. Implement obot-app-token + the identity skill in safety.agent; acceptance: bot comment posted from a working session. (D4)
4. Add app-smoke-test.yml to obot.roadmap; acceptance: dispatched run comments on #3 as the bot.
5. Credential retirement audit per §7; record the outcome on #3.
6. Document the identity rules (§2.1) in obot.roadmap AGENTS.md and the README repo table.