docs: propose credential lifecycle and GitHub App access

[freeqaz-openai]

What Problem This Solves

Enterprise Agents need repository access whose scope, approvals and cleanup survive turns and runtime replacement. Provider tokens alone cannot enforce an approved candidate, exact branch or original-work attribution.

Why This Change Was Made

Propose native Agent repository configuration and an Installation-selected CredentialGatewayDriver for mediation and credential lifecycle. Delivery starts with managed metadata, clone and fetch, then adds selected coding read workflows and exact-candidate Approve and publish. Any configured, authorized human may approve, including the requester; an Agent cannot. Independent-human approval and automatic authorization under explicit policy for bounded, allowlisted push/draft-PR operations are separate later modes. Broader durable Work and lifecycle controls follow the initial root work and subordinate helpers using the same scope.

User Impact

The proposed configuration and driver API are not implemented. The proposed GitHub profile keeps provider credentials outside Agent workloads and requires current online OCC authority for reads, writes and credential maintenance. Publication binds the candidate, refs, expected remote tip and PR metadata, preserving separate effect receipts and reconciling unknown outcomes without blind replay. Permission changes require fresh Pod/gVisor isolation; uncapped execution still uses finite leases.

This is a documentation proposal extending RFC 0027. It remains draft with a blank implementation issue pending acceptance.

Reading Guide

• Credential lifecycle and GitHub App access and detailed specification.
• Repository configuration and CredentialGatewayDriver.
• GitHub profile.
• Recovery and qualification.
• Series overview.
• Related drafts: #69, #70, #71.

Evidence

• Checked draft metadata, required sections, Markdown structure, links, anchors and whitespace; reran desktop/mobile rendering and independent cross-RFC review.
• Desktop preview uses a local Markdown render with GitHub-style CSS.
• Document checks only; provider, native runtime and deployment qualification require separate evidence.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 14, 2026, 6:42 PM ET / 22:42 UTC (Revision 17).

ClawSweeper review

What this changes

Adds a staged Enterprise GitHub access proposal covering repository configuration, protected credentials, scoped proxy credentials, human-approved publication, cleanup, and qualification requirements.

Merge readiness

⛔ Blocked before merge - 4 items remain

This remains a distinct, coherent RFC that is absent from main. No actionable patch defect was found, but the repository requires explicit RFC acceptance before merge.

Priority: P3
Reviewed head: 8c65dbb3d535d0805cd74cce5f6c368a82733106
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A coherent, carefully bounded RFC with useful document proof and no concrete patch findings.
Proof confidence	🐚 platinum hermit (4/6) ✨ media proof bonus	Sufficient (screenshot): The inspected committed preview demonstrates the proposal's rendered layout and diagrams. The latest proxy-credential text and Mermaid replacement were source-reviewed; runtime authorization and provider behavior are expressly future implementation gates, not claims proved by this screenshot.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): The inspected committed preview demonstrates the proposal's rendered layout and diagrams. The latest proxy-credential text and Mermaid replacement were source-reviewed; runtime authorization and provider behavior are expressly future implementation gates, not claims proved by this screenshot.
Evidence reviewed	8 items	Repository lifecycle requires acceptance: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted frontmatter before merging a new RFC. The proposed RFC correctly remains draft with its issue blank. Distinct work remains absent from main: The pinned main tree lacks the proposed RFC and supporting specifications; searching main for the credential gateway and repositoryAccess found no matches. The accepted Enterprise baseline supplies general broker and authorization requirements, not this GitHub configuration and publication contract. The GitHub releases endpoint returned an empty list. Latest revision and review continuity: The exact-head GitHub commit response identifies three changed Markdown files since the previous review: proxy-credential requirements, the main diagram, and matching qualification cases. Earlier structured review context contained no findings. A local parent diff failed because a required blob fetch returned HTTP 403; the GitHub commit patches supplied the revision comparison instead.
Findings	None	None.
Security	None	None.

How this fits together

OpenClaw Enterprise's proposed credential gateway sits between Agent repository requests and GitHub. It combines administrator-selected access, independently verified execution identity, and current control-plane authorization before using protected provider credentials.

flowchart LR
    Config[Administrator repository selection] --> Authority[Current control-plane authorization]
    Agent[Agent repository request] --> Connector[Trusted execution connector]
    Connector --> Gateway[Credential gateway]
    Authority --> Gateway
    Approval[Human-approved publication candidate] --> Gateway
    Gateway --> GitHub[Scoped GitHub operation]

Loading

Decision needed

Question	Recommendation
Should Enterprise adopt the proposed repository configuration and CredentialGatewayDriver contract with managed reads first and human-approved publication second?	Accept the staged direction: Approve the documented scope and minimal companion contracts, then record the implementation issue and accepted metadata.

Why: This adds a new configuration and integration direction, and README explicitly reserves RFC acceptance for the repository's discussion and acceptance process.

Before merge

• Resolve merge risk (P1) - The overview's pinned Enterprise implementation comparison could not be independently verified because the linked source returned HTTP 404.
• Resolve merge risk (P1) - The minimal identity, Work, and replacement contracts depend on separately unaccepted companion RFCs; accepting this document alone cannot establish their production guarantees.
• Complete next step (P2) - Record RFC acceptance through the required discussion process, then set status to accepted and link its implementation issue before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Proposal scope	6 Markdown documents, 3 diagram sources, 4 PNGs; 1,888 added text lines	Most detail sits in supporting specifications; the patch introduces no executable production code or tests.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Accept a clearly staged contract with explicit companion dependencies and implementation evidence gates, keeping production qualification separate from RFC approval.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Accept a clearly staged contract with explicit companion dependencies and implementation evidence gates, keeping production qualification separate from RFC approval.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR proposes future contracts and explicitly claims documentation checks only, rather than reporting a reproducible runtime defect.

Is this the best way to solve the issue?

Yes, as an RFC: staged delivery, existing authority ownership, and separate production qualification form a coherent design path; acceptance of the new integration contract remains a human decision.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 967d9aac7472.

Labels

Label justifications:

• P3: This is a design proposal with no deployed behavior change or demonstrated urgent regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The inspected committed preview demonstrates the proposal's rendered layout and diagrams. The latest proxy-credential text and Mermaid replacement were source-reviewed; runtime authorization and provider behavior are expressly future implementation gates, not claims proved by this screenshot.
• proof: sufficient: Contributor real behavior proof is sufficient. The inspected committed preview demonstrates the proposal's rendered layout and diagrams. The latest proxy-credential text and Mermaid replacement were source-reviewed; runtime authorization and provider behavior are expressly future implementation gates, not claims proved by this screenshot.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The inspected committed preview demonstrates the proposal's rendered layout and diagrams. The latest proxy-credential text and Mermaid replacement were source-reviewed; runtime authorization and provider behavior are expressly future implementation gates, not claims proved by this screenshot.

Evidence

What I checked:

• Repository lifecycle requires acceptance: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted frontmatter before merging a new RFC. The proposed RFC correctly remains draft with its issue blank. (README.md:78, 8c65dbb3d535)
• Distinct work remains absent from main: The pinned main tree lacks the proposed RFC and supporting specifications; searching main for the credential gateway and repositoryAccess found no matches. The accepted Enterprise baseline supplies general broker and authorization requirements, not this GitHub configuration and publication contract. The GitHub releases endpoint returned an empty list. (rfcs/0027-openclaw-enterprise.md:350, 967d9aac7472)
• Latest revision and review continuity: The exact-head GitHub commit response identifies three changed Markdown files since the previous review: proxy-credential requirements, the main diagram, and matching qualification cases. Earlier structured review context contained no findings. A local parent diff failed because a required blob fetch returned HTTP 403; the GitHub commit patches supplied the revision comparison instead. (rfcs/0034/github-app-v1-spec.md:444, 8c65dbb3d535)
• Security requirements remain explicit proposal gates: The proxy credential requires independently verified original execution/Work and current authorization; possession alone is insufficient. The qualification appendix covers copied credentials, wrong execution, closure, revocation, and upstream token substitution. These are documented future requirements, not claims of implemented enforcement. (rfcs/0034/lifecycle.md:391, 8c65dbb3d535)
• Rendered documentation evidence inspected: The prepared proof-image-1.png contained HTML and could not be decoded. The tracked review-preview.png was a valid 1080×2803 PNG and was inspected directly, along with all three diagram PNGs. It demonstrates readable proposal layout, tables, and diagrams, but predates the latest proxy paragraph and Mermaid replacement; those additions were reviewed in source. (rfcs/0034/review-preview.png, 8c65dbb3d535)
• Enterprise comparison has an inspection limitation: The overview explicitly relies on openclaw/openclaw-enterprise source at 3eeacb85d9e8e087bc3e74d792778e4ef3123412 for existing API, credential-delivery, and replacement claims. Reading its linked contracts file returned HTTP 404. Those external implementation claims remain independently unverified; this does not invalidate the documentation proof or establish a contributor defect. (rfcs/0027/runtime-access-overview.md:15, 8c65dbb3d535)

Likely related people:

• kevinlin-openai: Raw commit af708f0 adds rfcs/0027-openclaw-enterprise.md:386 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: af708f0ddb6f; files: rfcs/0027-openclaw-enterprise.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (16 earlier review cycles; latest 8 shown)

• reviewed 2026-09-09T00:08:06.095Z sha 2d4b35f :: needs real behavior proof before merge. :: none
• reviewed 2026-09-09T00:41:53.447Z sha 4043e1d :: needs real behavior proof before merge. :: none
• reviewed 2026-09-09T21:12:14.275Z sha f7de428 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-09T21:43:36.560Z sha 7dea5a4 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-11T07:48:03.154Z sha 265cc4f :: blocked before merge. :: none
• reviewed 2026-09-11T19:11:16.301Z sha 0670aeb :: blocked before merge. :: none
• reviewed 2026-09-11T19:31:12.142Z sha 3d79901 :: blocked before merge. :: none
• reviewed 2026-09-14T21:59:39.919Z sha 3d79901 :: blocked before merge. :: none