Provide a role-scoped GitHub gateway for Docker automations

[neubig]

Desired Behavior

Provide a repository-scoped GitHub gateway for Docker automations. The trusted control plane retains the GitHub credential, while triage, implementation, review, and watchdog workers receive separate role tokens. This is the independently reviewable permission boundary used by the software-factory recipe in #556.

Acceptance Criteria

• Role allowlists restrict writes to issue readiness, factory implementation branches, exact-commit review evidence, or guarded merge according to the selected role.
• Private repository snapshots are available for exact commits without handing the GitHub credential to a worker.
• Merge rejects changed heads, stale bases, missing acceptance statuses, failing/pending checks, and conflicts, and includes the reviewed SHA in the merge request.
• Workers cannot administer/delete repositories, write main directly, force push, or invoke an unguarded merge.
• Authorization and fail-closed merge tests pass without credentials or network access; setup documents the trust boundary and limits.

ready-for-dev: scope and acceptance criteria are defined.

[github-actions]

✅ ready-for-dev label applied

This issue meets the readiness criteria and is ready for contribution.
A contributor can now open a PR that links this issue (Fixes #<number>).

This is an automated readiness check posted by a workflow.

[neubig]

Additional ready-for-dev acceptance criteria from the live factory audit:

• The gateway must use a separately configured upstream GitHub token for each authenticated role, with no fallback to the interactive gh credential.
• Missing, empty, duplicate, or shared worker/upstream credentials must fail startup without printing values.
• Concurrent reviewer and developer requests, private archive downloads, and the complete watchdog merge gate must retain the calling role's credential throughout.
• Document repository-scoped fine-grained token permissions. Reviewers need read-only Contents plus review/comment/status permissions; only the developer and merge watchdog need Contents write. Raw GitHub credentials remain outside worker bundles and prompts.
• Add credential isolation and rejected-write tests; deployment switches only after the required scoped credentials are available.

This remains the scope of PR #559; the existing gateway boundary is the appropriate place for the fix.

[neubig]

Ready-for-dev acceptance update: allow an explicit FACTORY_GITHUB_WATCHDOG_TOKEN_ENV=FACTORY_GITHUB_DEVELOPER_TOKEN configuration so the watchdog can reuse the developer upstream credential. Keep separate worker grants and all watchdog operation/merge checks; triage and reviewer credentials must remain separate, and no implicit shared-token fallback is allowed.

[neubig]

Ready-for-dev correction after live credential verification: GitHub does not currently support the Checks API with fine-grained PATs (official PAT limitations); Actions read returns 200 but check-runs still returns 403 with checks=read. Preserve full Checks gating by allowing an optional host-only FACTORY_GITHUB_CHECKS_TOKEN from a repository-scoped GitHub App with Checks read. Use it only for authorized GET check-run reads, never role writes or worker grants. Existing role tokens remain valid for other operations; absent dedicated token retains App-capable role-token behavior. Update the permission documentation and test credential routing and exposure rejection.

[neubig]

Ready-for-dev implementation update: user requires fine-grained PATs only. Replace the unfinished dedicated Checks-token experiment with explicit FACTORY_CI_BACKEND=actions support. Preserve exact-head independent review/test statuses, current-base verification, and guarded merge. Read Actions workflow runs with Actions read, reject incomplete pagination, wrong-head, failed/pending runs, and missing configured required workflow IDs. Default checks backend remains for compatible deployments; Actions mode explicitly covers Actions plus commit-status publishers, not Checks-only third-party integrations. No classic PAT or GitHub App credential will be requested.