Bitbucket Integration
Gate Bitbucket pull request merges with cryptographic human approval via OAuth and commit statuses.
The Bitbucket integration connects your Bitbucket workspace to SignedApproval via OAuth 2.0. When a pull request targets a configured branch, SignedApproval creates a commit status (build status) on the PR's head commit. The PR cannot be merged until a human provides signed approval.
Connection data is stored in signedapproval_bitbucket_connections and signedapproval_bitbucket_repo_configs tables. Each repository can have its own branch patterns, auto-merge settings, and quorum requirements.
Connect your Bitbucket workspace
Go to Dashboard → Settings → Integrations → Bitbucket and click Connect Workspace. You'll be redirected to Bitbucket's OAuth consent screen.
Grant SignedApproval access to your workspace. The OAuth app requests permissions for pull requests and commit statuses.
Select repositories
After connecting, select which repositories require SignedApproval checks. For each repository, configure:
- Branch patterns — e.g.,
main,release/* - Auto-merge — Automatically merge PRs after approval
- Quorum — Number of approvals required (1 or more)
Configure Bitbucket branch permissions
In Bitbucket's repository settings, add a merge check that requires the SignedApproval build status to pass before merging. This ensures PRs cannot be merged without cryptographic approval.
Commit Status Flow
- Developer creates or updates a pull request targeting a configured branch.
- Bitbucket sends a webhook to SignedApproval.
- SignedApproval creates a "INPROGRESS" build status on the PR's head commit.
- An approval request is created, notifying the configured approver(s).
- After approval, the build status is updated to "SUCCESSFUL".
- If rejected, the build status is set to "FAILED".
The mapping between approval requests and commit statuses is tracked in signedapproval_bitbucket_commit_statuses.
OAuth Token Management
SignedApproval stores OAuth access and refresh tokens for your Bitbucket connection. Tokens are encrypted at rest. When an access token expires, SignedApproval automatically uses the refresh token to obtain a new one.
You can disconnect your workspace at any time from the integrations settings page. Disconnecting revokes the OAuth token and removes all repository configurations.
main and release/* while leaving feature branches unrestricted.