github-app-actuator

# GitHub App Actuator The actuator performs an already-authorized GitHub effect. It does not decide what should happen, and the proposing agent never receives a GitHub credential. ## Explicit operator override during bootstrap An explicit operator instruction takes precedence over this skill. On 2026-09-19, Erich authorized temporary use of his existing authenticated GitHub account for the scoped Book, Media and Hook PR work and the actuator follow-up, until the proper actuator is usable. Preserve the authorization's scope; this does not authorize unrelated work, merges, gate bypasses or credential export. For that authorized fallback, verify the account, repository and exact head/base without printing tokens, use the existing authentication, and report the actual personal-account author. Never claim an App receipt or bot authorship. Continue building the daemon-independent actuator and return to it once its configured operation and readback are proven. Source presence alone does not end bootstrap. Without an explicit applicable operator override, the App-only boundary below remains the default. Do not ask again for authorization already present in the task's verified user instructions. ## Non-negotiable boundary ```text agent proposal -> exact one-use grant -> protected actuator -> GitHub App token | | | +-- revoked +-- signed read-back receipt ``` - In the protected actuator path, the operator's PAT, OAuth token, `pdu_` account bearer, browser session, and ambient `gh` login are never publication inputs. - The GitHub App private key and installation token never enter agent memory, environment variables, command arguments, Git credential helpers, logs, or returned tool data. - The actuator accepts a fixed operation and bounded structured fields, not a shell command, URL, arbitrary HTTP request, or Git configuration. - Every grant binds the responsible actor and session, repository, operation, exact head/base, content digest, expiry, nonce, signing-key generation, and roadmap item or explicit sidequest reason. - One logical mutation produces one durable receipt. An ambiguous response is resolved by exact read-back, never by a blind retry. Same-UID policy files are guidance, not confinement. A durable installation must run the credential custodian as a separate OS identity or remote service and deny the agent account access to its keychain, private key, and service secrets. ## Use it 1. Finish and validate a coherent commit in a linked worktree. Fetch and reconcile before publication; keep inherited repository hooks inert when the local Port Daddy halt requires that. 2. Prepare the exact structured operation. Supported contract operations are `pull-request.publish`, `pull-request.update`, `pull-request.ready`, `pull-request.request-reviewers`, `pull-request.comment`, `pull-request.review-reply`, `pull-request.resolve-review-thread`, `pull-request.enqueue`, and `pull-request.inspect`. 3. Submit it only through the configured Fleetbot actuator. The canonical contract is `lib/github-publisher-contract.ts`; the protected Relay executor is `POST /v1/fleetbot/publish`. Do not invent a shell/CLI substitute. 4. Require the returned receipt to identify `port-daddy[bot]`, the exact repository and operation, source and GitHub head SHAs, responsible actor/session, roadmap scope, verification time, and token-cleanup result. 5. Read the provider state again. Match exact head/base, PR number/state, comment marker, or queue state as appropriate. Preserve the receipt with the work. 6. Continue owning the PR: answer reviews through the actuator, add tests, keep CI green, and verify the immutable merge result. ## Current admission status The Relay publisher now rejects the former `pdu_` account-bearer path. GitHub Actions can enroll an Ed25519 workload identity through OIDC, read a bounded standing publisher-grant snapshot, sign an exact capability, and verify the Relay-signed receipt. The protected workload client is [`../../scripts/fleetbot-workload.mjs`](../../scripts/fleetbot-workload.mjs); the reviewed-code smoke is [`../../.github/workflows/fleetbot-workload-smoke.yml`](../../.github/workflows/fleetbot-workload-smoke.yml). Do not overstate that foundation. The client exposes enrollment, read-only inspection, and typed requests for PR comments, review replies, ready-for-review, reviewer requests, merge-queue enrollment, and new-PR publication from a bounded committed-source package; [`../../.github/workflows/fleetbot-actuator.yml`](../../.github/workflows/fleetbot-actuator.yml) is the protected reviewed-code entry point for those writes. Its steady-state write path does not request OIDC or exchange identity again. Source presence is not deployment evidence: publishing is available only after the environment, grant operation, workload key, Relay receipt key, and deployed Relay version are verified together. Comments and review replies may target an ordinary same-repository PR at its capability-bound exact head; readiness, reviewer, enqueue and update operations remain restricted to uniquely receipted Fleetbot-owned branches. New publication creates such a branch from its capability-bound source tree and base; it does not adopt an existing ordinary branch. Phase A verifies the GitHub dispatcher; its agent and session fields remain explicitly labeled as dispatcher-supplied until the proposal broker admits them from durable identity state. Local harnesses do not yet have a proposal broker. For new publication, use the offline package builder [`../../scripts/fleetbot-publication.mjs`](../../scripts/fleetbot-publication.mjs) and the protected workflow's `publish` operation. Follow [`../../docs/operations/fleetbot-source-publication.md`](../../docs/operations/fleetbot-source-publication.md). The proposed source is data, never runner code. Publication creates a new governed App branch; it does not adopt an ordinary branch or authorize closing its predecessor. Verify the signed source head, App branch and exact Git tree, then the provider PR/commit readback. A source package is not a grant or proof that the protected deployment is configured. New publication uses the same pre-effect manifest and recovery-only path below; never retry its mutation job. The protected actuator prepares and uploads a signed, non-secret recovery manifest before its first mutation attempt. Do not rerun that mutation job: GitHub's upload-artifact tracker documents attempt-one artifacts becoming unavailable after a rerun begins ([actions/upload-artifact#585](https://github.com/actions/upload-artifact/issues/585)). Instead, dispatch the separate protected **Fleetbot receipt recovery** workflow with the original run id. It retrieves the original-run artifact and calls only `POST /v1/fleetbot/publisher-receipts/recover` with a fresh domain-separated read proof. Recovery returns an already finalized, Relay-signed receipt. It never reads the current PR, obtains a GitHub token, consumes another mutation capability, or calls the publish endpoint. Missing, running, failed, ambiguous, corrupt, and legacy-unbound intents stop without a fallback write. This recovers loss of Relay's final response; it does not claim that an ambiguous GitHub effect is safe to retry. Never blind-retry a write. Recovery currently requires the original publisher grant, workload identity, signing-key generation, and Relay receipt key to remain current. Expiry, revocation, or rotation fails closed; artifact retention does not extend authority. Planned cross-rotation recovery requires the separately reviewed key-lineage phase rather than accepting an untrusted historical key. Never copy the Actions workload seed into Codex, Claude Code, Antigravity, Gemini, Agy, or a local helper to bridge that gap. Follow [`../../docs/plans/FLEETBOT-AGENT-ACTUATOR-ROLLOUT.md`](../../docs/plans/FLEETBOT-AGENT-ACTUATOR-ROLLOUT.md). Direct use of an operator credential or ambient `gh` login does **not** satisfy the protected actuator boundary. An explicit temporary operator override above is a separately attributed fallback, never App-publication evidence. ## Missing actuator Do not turn infrastructure absence into authorship fraud. Preserve the commit, branch name, exact base/head, prepared PR body or comment, and required operation. Report which actuator operation or grant is missing. Without an applicable explicit operator override, publication remains pending; the code is recoverable but not delivered. If the operator already authorized the scoped fallback, use it and preserve truthful authorship instead of stopping at this paragraph. ## Personal-credential retirement ceremony This is exceptional and must name the one final allowed operation. 1. Publish the cutover through `port-daddy[bot]` and verify bot authorship and exact provider state. 2. Remove the operator login from every agent-visible `gh` host configuration, Git credential helper, environment injection, launcher, and CI secret. 3. Revoke the credential at GitHub. Local `gh auth logout` alone is not remote revocation. 4. Rotate any credential ever printed, copied into a prompt, exposed to a same-UID process, or stored in an agent-readable file. 5. Verify without printing secrets: no `GH_TOKEN`/`GITHUB_TOKEN`; no authenticated `gh auth status`; no credential returned for GitHub; unauthenticated `/user` returns 401; the App actuator can still perform a separately authorized test. 6. Record only token kind, storage location removed, revocation timestamp, verification results, and actor. Never record a token or recoverable prefix. ## Reject these shortcuts - Inventing a personal-account fallback without explicit applicable operator authorization, or broadening a scoped override into unrelated mutations. - Passing the App private key to a helper running as the agent. - Treating token expiry as proof of revocation. - Commenting as the operator and adding a bot signature in the text. - Retrying a timed-out write without provider read-back. - Re-running a mutation after losing Relay's final response instead of sending the original run id to the separate receipt-recovery workflow. - Claiming a policy prompt prevents credential use by a malicious same-UID process. ## Completion evidence - GitHub mutation author is the configured App, not the operator. - Exact mutation state and responsible-agent provenance read back. - Installation-token cleanup is confirmed or explicitly ambiguous. - No personal credential was supplied to the agent or actuator request. - For a retirement: local removal and GitHub-side revocation are both proven.