Skip to content

Pipeline Plan 57

Jump to bottom
Seth Ford edited this page Feb 14, 2026 · 2 revisions

The file is blocked by permissions. The plan is complete — let me present it here directly.

Implementation Plan: GitHub App for Native Integration

Architecture Decision: Dual-Mode Authentication

The core design is a dual-mode authentication system where GitHub App tokens are preferred when configured, with automatic fallback to PAT (via gh CLI). A new sw-github-app.sh module provides gh_app_api() — a drop-in replacement for gh api that uses App installation tokens when available.

Key Principles:

  • All existing gh api calls remain functional (PAT fallback)
  • App token management centralized in one module
  • JWT signing uses openssl (no new dependencies)
  • Installation tokens cached (1hr TTL) with automatic refresh
  • Config in .claude/daemon-config.json under github_app key

Files to Modify

New Files:

  1. scripts/sw-github-app.sh — App authentication, JWT signing, installation token management, guided install
  2. scripts/sw-github-app-test.sh — Test suite for App auth flow
  3. .github/app-manifest.json — App manifest for one-click installation

Modified Files: 4. scripts/sw-github-checks.sh — Route through App tokens when available 5. scripts/sw-github-deploy.sh — Route through App tokens when available 6. scripts/sw-github-graphql.sh — Route through App tokens for GraphQL 7. scripts/sw-daemon.sh — Add webhook event consumption alongside polling 8. scripts/sw-webhook.sh — Handle additional event types (PR, check_suite, deployment_status) 9. scripts/sw-pr-lifecycle.sh — Post PR reviews via App (bot identity) 10. scripts/sw-doctor.sh — Add Section 14: GitHub App validation 11. scripts/sw — Add github-app subcommand route 12. .claude/daemon-config.json — Add github_app config block 13. package.json — Register new test suite

Implementation Steps

Step 1: sw-github-app.sh — Core auth module (~400 lines). Functions: gh_app_configured(), gh_app_jwt() (RS256 via openssl), gh_app_installation_token() (cached), gh_app_api() (drop-in for gh api), gh_app_graphql(), cmd_install(), cmd_status(), cmd_test().

Step 2: .github/app-manifest.json — Permissions: checks:write, contents:read, deployments:write, issues:write, pull_requests:write, metadata:read, statuses:write. Events: issues, pull_request, check_suite, check_run, deployment_status.

Steps 3-5: Modify GitHub API modules — Add _gh_api() helper to sw-github-checks.sh, sw-github-deploy.sh, and sw-github-graphql.sh that routes through App tokens when available, with PAT fallback.

Step 6: Enhance sw-webhook.sh — Handle pull_request.opened, check_suite.requested, deployment_status events.

Step 7: Modify sw-daemon.sh — Add daemon_check_webhook_events() for instant processing. Config: webhook_mode = polling/hybrid/webhook_only.

Step 8: Modify sw-pr-lifecycle.sh — Add pr_post_review() and pr_post_comment() with App token.

Steps 9-12: Doctor, CLI, tests — Section 14 in doctor, CLI route, test suite, package.json registration.

Task Checklist

  • Task 1: Create scripts/sw-github-app.sh with JWT signing, token management, gh_app_api(), gh_app_configured()
  • Task 2: Create .github/app-manifest.json with required permissions
  • Task 3: Add github_app config block to .claude/daemon-config.json
  • Task 4: Modify sw-github-checks.sh — _gh_api() helper, replace all gh api calls
  • Task 5: Modify sw-github-deploy.sh — same pattern
  • Task 6: Modify sw-github-graphql.sh — same pattern for GraphQL
  • Task 7: Enhance sw-webhook.sh with additional event types
  • Task 8: Add daemon_check_webhook_events() to sw-daemon.sh
  • Task 9: Add bot PR reviews to sw-pr-lifecycle.sh
  • Task 10: Add Section 14 to sw-doctor.sh
  • Task 11: Add github-app route to scripts/sw
  • Task 12: Create scripts/sw-github-app-test.sh test suite
  • Task 13: Register in package.json, verify all 23 suites pass
  • Task 14: Run shipwright docs sync for AUTO sections

Testing Approach

  1. Unit tests (sw-github-app-test.sh): Mock binaries, verify JWT format, token caching, API routing, fallback
  2. Existing test suites: Verify no regressions in PAT mode
  3. Full suite: npm test — all 23 suites pass
  4. Manual: shipwright github-app status and shipwright doctor

Definition of Done

  • Native check runs via App (no more warnings)
  • Webhook receiver processes events instantly
  • PR reviews appear as bot
  • PAT fallback works transparently
  • Doctor validates App configuration
  • Guided install flow
  • All 23 test suites pass
  • CLAUDE.md AUTO sections updated

Clone this wiki locally