Use GitHub with permissioned agents by forcing every repo-changing action through policy-as-code and verifiable execution, not prompt instructions. In Claw EA, the baseline runtime is OpenClaw, and GitHub access is implemented via official API or an official MCP server with enterprise buildout controls, then constrained by a WPC and CST.
This matters because GitHub is a change control surface: a single mis-scoped token or a single “helpful” model decision can create branches, open pull requests, alter workflows, or leak code. Prompt-only “rules” are not enforcement, so you need machine-checked gates for write and admin actions.
Step-by-step runbook
1) Decide the GitHub connection path: official API or an official MCP server, and define which identity will be used (GitHub App, OAuth token, or other enterprise-approved method). Start with read-only scopes and only add write scopes when you have a hard approval gate.
2) Create a WPC = Work Policy Contract (signed, hash-addressed policy artifact; served by clawcontrols) that enumerates allowed repos, allowed operations, and escalation rules. Treat “merge”, “push”, “workflow changes”, and “secrets” as separate operations, even if they are all “write” in GitHub terms.
3) Issue a CST = scoped token (issued by clawscope) for the job, and pin it to the policy by hash when you can. Use job-scoped CST binding to reduce replay across jobs and to make “this token only existed for that run” a verifiable claim.
4) Run the agent in OpenClaw with strict tool policy and sandbox defaults. Put GitHub operations behind an explicit tool name so you can deny-by-default and only allow the minimal calls needed for the run.
5) Route model calls through clawproxy so you get Gateway receipts for each model call, then bundle them into a proof bundle for the run. Store the resulting artifact as a Trust Pulse when you need centralized viewing and audit workflows.
6) Operationally, set a two-phase flow: phase A is read and plan (list issues, read files, propose diff), phase B is apply (create branch, push commit, open PR), and phase B requires WPC approval gates. If phase B is denied, the agent should still produce a patch artifact and a PR-ready plan without touching GitHub.
Threat model
| Threat | What happens | Control |
|---|---|---|
| Prompt injection via issue text or PR comments | The agent is tricked into running “helpful” actions like pushing code, changing CI, or exfiltrating file contents into a comment. | Separate read from write in the WPC, default to read-only, and require explicit approval for write/admin actions. Constrain OpenClaw tool policy so GitHub write tools are not available in the same session as broad file or shell tools unless required. |
| Over-scoped GitHub credentials | A token with broad repo access is reused to modify unrelated repositories or sensitive org settings. | Issue CST per job and bind it to a narrow WPC policy hash; the job cannot “grow” permissions mid-run. Use least-privilege GitHub auth scopes and restrict to specific repos and orgs in your enterprise buildout. |
| Malicious or compromised tool/plugin | The GitHub tool silently performs extra API calls (extra repo reads, unexpected writes) beyond the user intent. | Require WPC approval gates for any write or admin capability. Keep GitHub operations auditable as discrete tool calls, and review the proof bundle post-run when the action touches protected repos. |
| Supply chain edits via workflow manipulation | The agent changes GitHub Actions workflows to run untrusted code or to publish artifacts, creating a CI-to-prod path. | In the WPC, treat “.github/workflows/*” edits as a higher-risk category requiring additional approval. Deny workflow file changes by default unless the job is explicitly a CI maintenance task. |
| Replay of an earlier “approved” run | An attacker replays an old token or re-submits an old plan to get the same write action executed again. | Use marketplace anti-replay binding with job-scoped CST binding so a token is tied to a single job context. Verify that the policy hash and scope hash match what was approved for that job. |
Policy-as-code example
This is a compact, JSON-like WPC sketch showing how teams typically gate GitHub. The key point is that “allowed” is enforced by the execution layer, not requested in a prompt.
{
"wpc_version": "v1",
"tool": "github",
"connection_mode": ["official_api", "mcp_server"],
"repos": [
"acme/payments-service",
"acme/shared-libraries"
],
"permissions": {
"read": ["issues:read", "pull_requests:read", "contents:read"],
"write_requires_approval": [
"contents:write",
"pull_requests:write",
"workflows:write",
"actions:write",
"administration:*"
]
},
"path_rules": [
{ "glob": ".github/workflows/**", "default": "deny", "override": "approval_required" },
{ "glob": "**/secrets/**", "default": "deny" }
],
"change_controls": {
"require_plan_before_write": true,
"require_human_approval_for_write": true
},
"token_binding": {
"require_cst": true,
"pin_policy_hash": true
}
}
In practice, the WPC is signed and hash-addressed in clawcontrols, then fetched and verified before the job runs. The CST from clawscope can be pinned to the WPC hash so the job cannot swap policies without failing closed.
What proof do you get?
For model traffic, clawproxy emits Gateway receipts for each model call, and Claw EA can package those receipts into a proof bundle for the run. This lets you answer “which model calls led to the plan” without trusting a mutable log stream.
For authorization, you can show which WPC was used (by policy hash) and which CST was presented (with scope hash and optional policy hash pinning). Combined with job-scoped CST binding, this gives an auditable link from an approved policy to a specific run, instead of “someone said it was approved”.
When you need centralized viewing, store the resulting artifact as a Trust Pulse for audit and review. If a repo write occurred, the proof bundle is the object you hand to security or compliance to validate what was permitted and what actually executed.
Rollback posture
| Action | Safe rollback | Evidence |
|---|---|---|
| Branch created and commits pushed | Delete the branch or force-protect the default branch so only reviewed PRs can merge. | Proof bundle links the run to the WPC and CST used; Git history shows the commit set that must be reverted. |
| Pull request opened | Close the PR and block auto-merge; require CODEOWNERS review on protected paths. | Run artifacts show the intended diff and the policy category (read vs write) that was approved. |
| Workflow files modified | Revert the workflow commit immediately, then rotate any exposed secrets and re-run CI from a known-good commit. | WPC path rules show whether workflows were allowed; the proof bundle identifies the run that produced the change. |
| Unexpected API calls (extra reads or writes) | Revoke the GitHub credential, revoke the CST, and quarantine the agent configuration until reviewed. | CST issuance and revocation records, plus the policy hash used, support a tight incident timeline. |
OpenClaw sandboxing and tool policy reduce local blast radius if a task also involves running tests or generating artifacts. Keep “elevated” host execution off unless you have a clear need, and treat it as a separate approval path.
FAQ
Is this a native GitHub connector in Claw EA today?
No. GitHub can be connected via official API and MCP-compatible tooling with enterprise buildout controls, but it should be treated as an implementable integration rather than an out-of-the-box connector.
Why is prompt-only control not enough for GitHub actions?
Prompts are advisory and can be overridden by injected text from issues, PRs, or repo files. A permissioned execution layer enforces WPC rules and CST scope constraints even when the agent is pressured to do more.
What GitHub permissions should an agent start with?
Start with read-only capabilities needed to plan work: repo contents read, issues read, and pull request read. Add write permissions only behind WPC approval gates, and separate workflow edits from normal code edits.
What does “approval gate” mean operationally?
It means the run must present a WPC that explicitly allows the write category, and your workflow requires an explicit approval decision before those tool calls are enabled. If approval is not granted, the agent can still produce a patch and plan without touching GitHub.
What evidence is available after a run changes a repository?
You can retain the WPC policy hash, CST scope hash (and optional policy hash pinning), plus Gateway receipts and a proof bundle covering model calls. When stored as a Trust Pulse, reviewers have a single artifact to inspect for what was permitted and what executed.