Bitbucket is a high-impact surface for enterprise agents because a single token can grant read access to proprietary code, and write access can change what gets built, tested, and deployed. If you want an agent to touch Bitbucket safely, you need permissioned execution that is enforced by policy-as-code, not prompt-only guidance.
Claw EA runs OpenClaw as the baseline agent runtime and adds an execution permission layer: WPC = Work Policy Contract gates what the agent may do, CST = scoped token limits where it can do it, and clawproxy emits gateway receipts for model calls that can be packaged into proof bundles for audit and replay checks.
Step-by-step runbook
-
Define the Bitbucket actions you actually need, separated into read-only and write/admin. Start with read-only for repository browsing, diff review, and PR summarization, then add narrowly-scoped write actions (commenting on PRs, opening PRs) only when there is an owner-approved use case.
-
Create a WPC = Work Policy Contract that encodes allowed repositories, allowed operations, and required human approvals. Treat “merge”, “branch deletion”, “permission changes”, and “pipeline config changes” as denied by default unless you have a formal change process.
-
Provision Bitbucket authentication via official API with enterprise buildout controls. Use least-privilege auth scopes and separate identities for read actions versus write actions, so a compromise in a read workflow does not silently become a write workflow.
-
Issue a CST = scoped token (issued by clawscope) to the agent job, scoped to the specific WPC and the specific tool capabilities. Enable optional policy hash pinning so the CST is only valid when the exact WPC hash is in force.
-
Run the agent inside OpenClaw with sandboxing and a tight tool allowlist. Use OpenClaw’s separation of sandbox, tool policy, and elevated execution to ensure that a Bitbucket workflow cannot “accidentally” become shell access or filesystem traversal.
-
Route model calls through clawproxy so you get gateway receipts. Store the resulting proof bundle alongside the Bitbucket change record (PR link, commit SHA) so an auditor can verify what the model was asked and what it returned.
Threat model
Bitbucket risk is not just “bad code suggestions”. The more common enterprise failures are token misuse, unintended write scope, and agent-triggered changes that bypass normal review and traceability.
| Threat | What happens | Control |
|---|---|---|
| Prompt injection via issue, PR comment, or README | The agent is tricked into exfiltrating code, changing a pipeline file, or modifying security checks while claiming it is following instructions. | WPC denies sensitive write paths by default; OpenClaw tool allowlists limit what tools can run; require approval gates for write/admin actions. |
| Over-privileged Bitbucket token | A “helper” token quietly has admin rights, enabling repo permission changes, branch deletion, or bypassing protection rules. | Split identities and scopes; WPC approval gates for write/admin actions; CST scoping to restrict which actions can be invoked in the job. |
| Unreviewed changes to CI configuration | The agent edits build definitions or pipeline scripts and introduces supply-chain risk, or disables security scanning. | WPC denies changes to CI and security-critical files unless explicitly allowed; require PR-based workflow only, no direct pushes. |
| Cross-repo data leakage | An agent working in one project reads another project’s repo because the token is org-wide, then summarizes proprietary code into an external model prompt. | WPC restricts repositories by allowlist; CST scope hash ties the job to that policy; route model calls through clawproxy for receipts and review. |
| Replay or “same token, new job” misuse | A valid credential is reused later to run different instructions against the same repos without the original approvals. | Marketplace anti-replay binding using job-scoped CST binding; require per-job CST issuance with short TTL and policy hash pinning. |
Policy-as-code example
This is a simplified, JSON-like sketch of how teams typically encode Bitbucket constraints in a WPC. The key is that the policy is machine-enforced at execution time, not “suggested” in a system prompt.
{
"tool": "bitbucket_via_official_api",
"policy": {
"repos_allowlist": [
"WORKSPACE_A/proj-web",
"WORKSPACE_A/proj-api"
],
"read": {
"allow": ["list_repos", "get_file", "get_diff", "list_prs", "get_pr"]
},
"write": {
"allow": ["create_branch", "create_pr", "comment_pr"],
"deny": ["merge_pr", "delete_branch", "change_repo_permissions", "direct_push_main"],
"approval_required": true
},
"paths": {
"deny_globs": [
"**/bitbucket-pipelines.yml",
"**/.pipeline/**",
"**/.github/**",
"**/SECURITY*"
]
},
"auth": {
"least_privilege_scopes_required": true,
"separate_identities_for_read_vs_write": true
},
"attestation": {
"require_gateway_receipts": true,
"emit_proof_bundle": true
}
}
}
What proof do you get?
For any model calls routed through clawproxy, you receive gateway receipts that can be independently checked. These receipts let you answer operational questions like “which model responded”, “what inputs were sent”, and “what output the agent received”, tied to the job context.
Claw EA can package those receipts with job metadata into a proof bundle. In practice, you attach the proof bundle identifier to the PR or change ticket so audit can verify that the agent stayed within the WPC and that the run is not a replay of an older authorization.
If you need a central place for review, you can store the bundle as a Trust Pulse artifact for audit/viewing. This does not replace code review, but it makes agent activity verifiable in the same way you expect build logs and change records to be verifiable.
Rollback posture
Bitbucket-integrated agents should have explicit rollback actions that are safe, fast, and do not depend on the agent behaving well after a failure. You want to be able to freeze changes, revoke authority, and reconstruct what happened from receipts and proof bundles.
| Action | Safe rollback | Evidence |
|---|---|---|
| Agent made an incorrect code change in a branch | Close the PR, delete the agent branch, and revert via normal SCM practices. Keep “merge” denied for the agent unless explicitly approved. | PR history plus proof bundle for the run; gateway receipts for the model calls that proposed the diff. |
| Agent attempted a write action outside policy | Fail closed at the WPC gate and treat it as an incident signal. Do not widen scope mid-run; create a new job with a new CST if an exception is approved. | WPC hash and CST scope hash for the job; proof bundle showing blocked attempts and the run context. |
| Credential suspected compromised | Revoke the CST and rotate the Bitbucket credential used via official API. Re-run only after reviewing the WPC and reducing scope. | CST issuance and revocation records; proof bundle showing the last permitted actions and when they occurred. |
| Untrusted plugin or misconfigured tool policy | Disable the extension, tighten OpenClaw tool allowlists, and rerun OpenClaw security audit checks. Restore service only after a minimal policy set passes review. | OpenClaw configuration diff plus the proof bundle for affected jobs; gateway receipts where applicable. |
FAQ
Why is prompt-only control not enough for Bitbucket agents?
Prompts do not enforce permission boundaries when the agent is under pressure from injected instructions or ambiguous tasks. A WPC is enforced at execution time, and a CST constrains what the job can actually invoke even if the model “decides” otherwise.
Is this a native Bitbucket connector in Claw EA today?
No. Bitbucket can be connected via official API with enterprise buildout controls, and you should treat it as an integration project with explicit scope and review.
What actions should be allowed first?
Start with read-only operations that support review: listing PRs, reading diffs, and summarizing changes. Add write actions later, and keep merge and permission changes behind explicit approval gates in the WPC.
How do gateway receipts help in an incident?
They give you a verifiable record of model calls routed through clawproxy, tied to the job context. Combined into a proof bundle, they support “what happened” reconstruction without relying on the agent’s self-report.
How does this relate to OpenClaw sandboxing?
OpenClaw sandboxing reduces blast radius for tool execution, while tool policy controls what tools are callable. Claw EA’s WPC and CST add permissioned, job-scoped constraints so Bitbucket access is governed as an execution contract, not an instruction.