Bitbucket Cloud Configuration#
Cartography needs a Bitbucket Cloud credential and at least one workspace slug to sync workspaces, projects, repositories, and members.
Note
--bitbucket-workspaces is required. Bitbucket permanently removed the “list every workspace I can see” endpoint in 2026 (Atlassian’s CHANGE-2770). Cartography must now always be provided with the workspace slug(s).
Authentication#
API token or Access token#
Both use the same Authorization: Bearer <token> header, so either works with --bitbucket-auth-method token (the default):
An API token is tied to a user account. Create one from your Atlassian account settings under “API tokens with scopes”, selecting Bitbucket as the app and granting the scopes listed below.
An Access token is tied to a repository, project, or workspace instead of a user, so it keeps working if the creating user’s account is later deactivated. Create a workspace-level access token from the workspace’s settings under “Access tokens” - a repository- or project-level token can’t see anything outside its own scope, so it can’t complete a full sync.
Store the token in an environment variable and point Cartography at it:
export BITBUCKET_TOKEN=<your token>
cartography --bitbucket-token-env-var BITBUCKET_TOKEN ...
OAuth client#
Bitbucket Cloud has no client-credentials grant (no machine-to-machine mode with zero human interaction), so this needs one manual, one-time step to obtain a refresh token. After that, Cartography exchanges the refresh token for a new ~2-hour access token automatically for the life of every sync - you never repeat the manual step unless the refresh token is revoked.
Create the OAuth client. In the workspace, go to workspace settings > Apps and features > OAuth clients > Create OAuth Client.
Details tab: give it a name, e.g.
cartography.Authorization tab: set the grant type to Authorization Code, and enter a callback URL. Any URL works, even one that doesn’t resolve to anything, such as
https://localhost/callback- you only need to read thecodeparameter off the URL you get redirected to in step 2, not have anything actually running there.Scopes tab: check the scopes listed under Required Permissions above.
Save. Bitbucket shows the client’s Key (client ID) and Secret - the secret is only shown once, so save it now.
Get an authorization code. Visit this URL in a browser, signed in as a user with access to the workspace, substituting the client key:
https://bitbucket.org/site/oauth2/authorize?client_id=<client key>&response_type=codeApprove the consent screen. You’ll be redirected to your callback URL with a
codequery parameter, e.g.https://localhost/callback?code=<code>- the browser will likely show a connection error at that point, which is expected. Copy thecodevalue out of the address bar. It’s single-use and expires within a couple of minutes, so move on to the next step right away.Exchange the code for a refresh token. Run this once, from a machine you trust with the client secret:
curl -X POST -u "<client id>:<client secret>" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=authorization_code \ -d code="<code from step 2>"
The response is JSON containing a
refresh_tokenfield. Save it - this is the long-lived credential Cartography actually uses.Run Cartography with the client key, client secret, and refresh token:
export BITBUCKET_OAUTH_CLIENT_SECRET=<client secret> export BITBUCKET_OAUTH_REFRESH_TOKEN=<refresh token from step 3> cartography \ --bitbucket-auth-method oauth \ --bitbucket-oauth-client-id <client key> \ --bitbucket-oauth-client-secret-env-var BITBUCKET_OAUTH_CLIENT_SECRET \ --bitbucket-oauth-refresh-token-env-var BITBUCKET_OAUTH_REFRESH_TOKEN \ ...
Required Permissions#
API Token#
For an API token, grant these read-only scopes:
Scope |
Used for |
|---|---|
|
Reading workspaces and workspace membership. |
|
Listing projects within a workspace. |
|
Listing repositories within a workspace. |
Access Token#
For an Access token, create a workspace-level token and grant these scopes:
Scope |
Used for |
|---|---|
Account: Read |
Listing workspace members. |
Projects: Read |
Listing projects within a workspace. |
Repositories: Read |
Listing repositories within a workspace. |
OAuth Client#
For an OAuth client, grant these scopes:
Scope |
Used for |
|---|---|
Account: Read |
Listing workspace members. |
Projects: Read |
Listing projects within a workspace. |
Repositories: Read |
Listing repositories within a workspace. |
All permissions above are read-only; Cartography never writes to Bitbucket.
Configure Cartography#
Option |
Environment variable indirection |
Default |
Description |
|---|---|---|---|
|
- |
none |
Comma-separated workspace slugs to sync. Required. |
|
- |
|
Either |
|
Reads a Bitbucket API or Access token |
none |
Required when |
|
- |
none |
Required when |
|
Reads the OAuth client secret |
none |
Required when |
|
Reads the OAuth refresh token |
none |
Required when |
Run Cartography#
export BITBUCKET_TOKEN=<your token>
cartography \
--neo4j-uri <uri> \
--selected-modules bitbucket \
--bitbucket-workspaces my-workspace \
--bitbucket-token-env-var BITBUCKET_TOKEN
List every workspace in one run, for example --bitbucket-workspaces team-a,team-b. A user who belongs to several workspaces is a single node, so syncing workspaces in separate runs can remove that user’s other workspace memberships until those workspaces sync again.
Troubleshooting#
Symptom |
Likely cause |
|---|---|
|
Token or refresh token is invalid or expired. |
|
The slug is misspelled, or the credential does not belong to that workspace. |
|
An OAuth client or Access token is missing Account: Read, or an API token is missing |
|
Bitbucket Cloud rate limit hit. Cartography retries with backoff automatically. |