docs: GitHub App setup runbook (closes #450)

[chubes4]

Closes #450.

Summary

Adds docs/github-app-setup.md — the operator runbook for migrating from a classic-PAT credential profile to a GitHub App installation behind GitHubCredentialResolver.

This is only documentation. No code changes. The mode: 'app' code path has been live in inc/Support/GitHubCredentialResolver.php for some time; what was missing was a written-down procedure for actually performing the migration on a host.

What the runbook covers

• When to do this: bot identity, allowed_repos scoping, per-call token minting, removing single-human dependency.
• Prerequisites + concept primer: PAT vs App, how the resolver mints + caches installation tokens (JWT → installation access token → transient cache with 60s expiry skew).
• Step-by-step migration:
  1. Create the App on github.com with the permissions DMC actually uses (Contents read, Issues r/w, PRs r/w, Checks read, Statuses read, Actions read).
  2. Install the App on the org.
  3. Land the App ID + Installation ID + PEM private key on the host (PEM goes through the datamachine/update-settings ability so the sanitizer preserves newlines).
  4. Define github_credential_profiles with the App as default and the PAT demoted to a named fallback.
  5. Verify via wp datamachine-code github status.
  6. Smoke-test bot identity by filing a throwaway issue and confirming author_type: Bot via gh api.
  7. Test the PAT fallback path so operators know how to opt back into human identity when they need to.
• Troubleshooting: github_pat_not_configured on a wrongly-typed App profile, 401 from POST /app/installations/:id/access_tokens (App/install/PEM mismatch), poisoned token cache, openssl_sign() not available + the firebase/php-jwt fallback.
• Behavioral notes: per-call token minting, expiry skew, audit trail in the org log, when removing the PAT entirely makes sense.

Written from a live execution

Every command in the runbook was actually executed on extrachill.com against the Extra-Chill org's homeboy-ci App (app_id 3034937, installation_id 114752821). The smoke step was verified by filing Extra-Chill/extrachill-roadie#21 through datamachine/create-github-issue and confirming via gh api:

{"author":"homeboy-ci[bot]","author_type":"Bot","number":21,"state":"closed"}

So this runbook isn't theoretical — the procedure is exactly what worked.

Why DMC owns this doc

Per the discussion on #450: GitHubCredentialResolver, the mode: 'app' runtime, the datamachine/update-settings sanitizer for github_app_* fields, and wp datamachine-code github status all live in this plugin. Putting the runbook here means any DMC consumer (extrachill-roadie, future Studio integrations, CI tooling) has one canonical migration story to point at.

Out of scope (deferred / pre-existing follow-ups)

• Per-user GitHub OAuth. A team member with a linked GitHub account should commit/comment as themselves on GitHub. That lives in extrachill-users, not here.
• Removing the legacy single-cred surface entirely. The top-level github_pat / github_auth_mode / github_app_* settings still exist alongside github_credential_profiles. They coexist deliberately for back-compat; collapsing them is a separate cleanup.
• credential_selector plumbing through every issue/PR/comment ability. Some abilities accept the selector explicitly today, others rely on the default profile. Out of scope for this runbook; tracked separately if it needs filling in.

Notes for reviewer

• No CHANGELOG edit (homeboy owns release notes).
• Conventional commit (docs: ...).
• The runbook references concrete paths (/root/.secrets/<app-slug>.private-key.pem) and concrete numeric IDs (Extra-Chill's) as examples — those are documented as examples, not hardcoded. The procedure is org-neutral.

[homeboy-ci]

Homeboy Results — data-machine-code

Lint

✅ lint — passed

Deep dive: homeboy lint data-machine-code --changed-since 9b9c76c

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-code-lint-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-code-lint-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine-code/actions/runs/26519148555

Test

✅ test — passed

ℹ️ No impacted tests found for --changed-since 9b9c76c
ℹ️ Run full suite if needed: homeboy test data-machine-code
Deep dive: homeboy test data-machine-code --changed-since 9b9c76c

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-code-test-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-code-test-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine-code/actions/runs/26519148555

Audit

✅ audit — passed

Deep dive: homeboy audit data-machine-code --changed-since 9b9c76c

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-code-audit-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-code-audit-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine-code/actions/runs/26519148555

Tooling versions

• Homeboy CLI: homeboy 0.199.2+a70a794
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: 24893c5d
• Action: unknown@unknown