setup

Bitbucket

Purpose

Collects Bitbucket Cloud workspaces, projects, repositories, and workspace members.

tip

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

  1. 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, and read: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.
  2. In Subimage, enter the workspace slugs in bitbucket_workspaces, keep bitbucket_auth_method as token, and enter the token in bitbucket_token.
  3. Save the module and run a sync.

OAuth client

  1. 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.

  2. Signed in as a workspace member, open https://bitbucket.org/site/oauth2/authorize?client_id=<client key>&response_type=code and approve. Copy the code parameter from the URL you are redirected to. It expires within minutes.

  3. 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>"
  4. In Subimage, set bitbucket_auth_method to oauth, enter the workspace slugs, client key, client secret, and the refresh_token from 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.