Bitbucket
Purpose
Collects Bitbucket Cloud workspaces, projects, repositories, and workspace members.
Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.
Required Fields
| Field | Secret? | Description |
|---|---|---|
bitbucket_workspaces |
No | Comma-separated workspace slugs to sync |
bitbucket_auth_method |
No | token (default) or oauth |
bitbucket_token |
Yes | API token or workspace Access token. Required for token auth |
bitbucket_oauth_client_id |
No | OAuth client key. Required for oauth auth |
bitbucket_oauth_client_secret |
Yes | OAuth client secret. Required for oauth auth |
bitbucket_oauth_refresh_token |
Yes | Refresh token from the one-time consent. Required for oauth auth |
Bitbucket has no endpoint that lists a credential's workspaces, so name every workspace you want to sync. List them all in one module: a user who belongs to several workspaces is one node, and its memberships come from every listed workspace.
Setup Steps
API token or Access token
- Create one of these credentials:
- An API token, from your Atlassian account settings under API tokens with scopes. Select Bitbucket as the app and grant
read:workspace:bitbucket,read:project:bitbucket, andread:repository:bitbucket. - A workspace Access token, from the workspace's settings under Access tokens. Grant Account: Read, Projects: Read, and Repositories: Read. It is not tied to a user, so it keeps working when people leave. Repository and project Access tokens cannot see the whole workspace.
- An API token, from your Atlassian account settings under API tokens with scopes. Select Bitbucket as the app and grant
- In Subimage, enter the workspace slugs in
bitbucket_workspaces, keepbitbucket_auth_methodastoken, and enter the token inbitbucket_token. - Save the module and run a sync.
OAuth client
In the workspace, go to Workspace settings → Apps and features → OAuth clients and create a client with the Authorization Code grant, any callback URL (for example
https://localhost/callback), and the Account: Read, Projects: Read, and Repositories: Read scopes. Copy the key and secret.Signed in as a workspace member, open
https://bitbucket.org/site/oauth2/authorize?client_id=<client key>&response_type=codeand approve. Copy thecodeparameter from the URL you are redirected to. It expires within minutes.Exchange the code for a refresh token:
curl -X POST -u "<client key>:<client secret>" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=authorization_code \ -d code="<code>"In Subimage, set
bitbucket_auth_methodtooauth, enter the workspace slugs, client key, client secret, and therefresh_tokenfrom the response, then save and run a sync. Subimage exchanges the refresh token for a short-lived access token on each sync.
Notes
- The sync is read-only.
- If the credential cannot read workspace members, the sync keeps the members it stored earlier instead of deleting them.
Troubleshooting
- Bitbucket Unauthorized: the token is wrong, expired, or revoked. Create a new one.
- Bitbucket Forbidden: the credential is missing one of the read scopes above.
- Bitbucket Workspace Not Found: a slug is misspelled, or the credential does not belong to that workspace.
- Bitbucket OAuth Refresh Failed: the client key, secret, or refresh token was rejected. Repeat steps 2 and 3 to get a new refresh token.