Skip to main content
Connect a Bitbucket Cloud workspace to Oleria to see who has access to your code: workspace members, the groups that hold permissions, every project and repository, and the deploy keys and public repositories that grant access outside your members. Oleria reads this data from the Bitbucket Cloud REST API with an Atlassian API token, so you can see where access is over-provisioned and take action directly from Oleria. Each integration covers one Bitbucket workspace. To bring in several workspaces, add one integration for each.

​
What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Bitbucket workspace:
  • Accounts - every workspace member, with their name and nickname. Oleria also keeps each member’s Atlassian account ID, the same ID your Atlassian Cloud integration records for that person.
  • Account roles - each member’s workspace permission: Workspace Administrator or Workspace Member. Workspace administrators are marked as admins. If Bitbucket reports a member who can create projects, they appear as Workspace Member (can create projects). If Bitbucket still reports the older collaborator permission, which it is retiring, those members appear as Workspace Collaborator and are marked as external users.
  • User groups - every group that holds a permission on a project or repository, plus groups without permissions and group members when Bitbucket allows Oleria to read them. See Known limitations.
  • Resources - every project and repository in the workspace, and which project each repository belongs to.
  • Access - who can reach each project and repository, and with which permission (read, write, admin, or create-repo on a project):
    • Each member’s effective access to each repository, whether it comes from a direct grant, a group, or the project.
    • Group grants on projects and repositories.
    • Direct user grants on projects.
    • Workspace administrators’ implicit admin access, shown through the Workspace Administrator role’s admin access to all projects and repositories.
    • Anonymous read access to public repositories. When any repository in the workspace is public, Oleria adds an account named Anyone on the internet with read access to each public repository.
  • Non-human identities (NHIs) - repository and project deploy keys, with their label, creation date, and last-used date. Each key also appears as a credential, managed by its owner or, if the owner has left the workspace, the member who added it. Bitbucket deploy keys are read-only.
Oleria refreshes this data on its regular sync schedule. When a repository is made private, or a grant is removed in Bitbucket, the access disappears from Oleria on the next sync.
Bitbucket has no audit-log API, so this integration doesn’t collect activity. If your Bitbucket workspace is linked to an Atlassian organization with Atlassian Guard, its events appear in the organization’s audit log, and the Atlassian Cloud integration brings them into Oleria. If that integration uses a scoped organization API key, the key needs read:events:admin.

​
Prerequisites

  • A Bitbucket Cloud workspace. Bitbucket Data Center and Bitbucket Server aren’t supported.
  • A user with the Workspace Administrator permission in that workspace, to own the API token. Bitbucket shows workspace members and permissions only to workspace administrators, and Oleria acts with this user’s permissions.
  • The workspace slug - the part after bitbucket.org/ in your workspace URL. For example, the slug for https://bitbucket.org/acme is acme.
  • Admin access to the Oleria workspace.
Create the API token as a dedicated Bitbucket administrator user instead of a named person’s account. If that user leaves the workspace or loses the Workspace Administrator permission, syncs and actions stop working.

​
Create an Atlassian API token

Bitbucket Cloud authenticates API calls with Atlassian API tokens. Bitbucket app passwords were retired on July 28, 2026, Bitbucket access tokens can’t read or change permissions, and OAuth consumers can read permissions but can’t change them, so Oleria accepts only an API token.
1

Sign in as the workspace administrator

Sign in to id.atlassian.com as the workspace administrator who will own the token.
2

Create an API token with scopes

Go to Security -> Create and manage API tokens -> Create API token with scopes. Give the token a name (for example, Oleria) and an expiry date, then select Bitbucket as the app.
3

Select the scopes

Select these scopes. Atlassian scopes don’t include each other, so select every scope in the list, even where a broader-sounding one is already selected.
4

Copy the token

Select Create, then copy the token. If you want to enter the email address of the Atlassian account that owns it in the connection form, note it too. The email is optional.
Atlassian shows the token value only once, when you create it. Copy it now and store it securely.
API tokens expire, at most one year after you create them. Before the token expires, create a new one and update the integration in Oleria. See Verify the integration.
The exact location of these settings can change over time. If the steps above don’t match what you see, refer to Atlassian’s own documentation.

​
Connect Bitbucket to Oleria

1

Open the integration

Go to your Oleria workspace, select Integrations -> select Bitbucket.
2

Complete the connection form

Fill in the connection form:
3

Confirm the connection

Select Authenticate. Before it saves anything, Oleria checks that:
  • The API token works. Bitbucket answers some requests without credentials, so Oleria confirms the token was actually accepted.
  • The workspace exists and the token’s owner can see it.
  • The token’s owner has the Workspace Administrator permission, which Bitbucket requires to list members and permissions. This check needs the read:workspace:bitbucket scope.
  • The token can read deploy keys, which requires admin:repository:bitbucket and admin:project:bitbucket. Oleria checks the first repository and the first project, so a workspace with no repositories or projects passes. If either scope is missing, the error names it.
If a check fails, Oleria shows which one and how to fix it. Find the newly connected workspace on the Connected tab of your Oleria Integrations page. You can’t connect the same workspace twice.
During a sync, if the token can’t read one repository or project, Oleria skips it and keeps syncing the rest. If the token is missing a scope, or most repositories refuse access, the sync fails and reports it instead of showing incomplete data.

​
Verify the integration

Confirm the Bitbucket workspace appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, check that members, projects, repositories, groups, and deploy keys appear in your Oleria workspace. The first sync can take a few hours for a large workspace. See Known limitations.
When you edit the integration, you can change the Atlassian account email and the API token. Leave API token blank to keep the stored token. A new token must belong to a Workspace Administrator of the same workspace, or Update fails. If you renamed the workspace in Bitbucket, updating the integration picks up the new slug. If the token expires or is revoked, syncs fail until you update the integration with a new token. An expired token is reported as rejected when you select Update.

​
Remediation actions

Oleria can take these actions in Bitbucket. Each one runs with the permissions of the user who owns the API token, and needs the scopes listed in Create an Atlassian API token. Revoke anonymous access needs only admin:repository:bitbucket, which the integration already requires. The group actions need admin:workspace:bitbucket. The Oleria app doesn’t show a Revert button yet for Revoke permission to a repository or project, Revoke anonymous access, Revoke access to an externally shared asset, Add user to group and Create group, so these can’t be reverted from the app. Before it offers an action, Oleria checks that the token works and that its owner has the Workspace Administrator permission. Bitbucket doesn’t report which scopes a token has, so Oleria can’t check the remediation scopes in advance. If a scope is missing, the action fails when it runs, the error names the missing scope, and Bitbucket makes no change.
The group actions use Bitbucket’s older groups API (version 1.0), because the current API has no way to change groups. Atlassian still supports that API for groups, but it hasn’t confirmed that it accepts API tokens, or which scope it needs. Oleria checks this API before it offers the group actions. If Bitbucket refuses, Oleria shows the group actions as not enabled for the integration, and running one fails with an error that says Bitbucket refused, instead of reporting a change that didn’t happen. In that case, manage groups in Bitbucket or your Atlassian organization.
Keep these limits in mind when you use these actions:
  • Revoke permission removes only a direct grant. If the user’s access comes from a group, from the project, or from being a workspace administrator, there’s no direct grant to remove, so the action fails with an error saying the user has no direct permission. If the access comes from a direct grant on the project, run the action on the project instead.
  • Access can remain after a revoke. When the user also has access through a group, the project, or the Workspace Administrator permission, the direct grant is still removed and the action succeeds, but its result says that access remains and which permission the user still has. For a project, Bitbucket can’t report one user’s group-based access, so the result names the groups that hold permissions on the project and says the remaining access couldn’t be confirmed.
  • External accounts are collaborators and non-members. An external account is one whose workspace permission is Workspace Collaborator, or one that holds a direct permission without being a workspace member. With no account named, Revoke access to an externally shared asset removes only people’s permissions; app users and teams are left as they are. Running Remove access for external accounts on a workspace member fails; use Revoke permission instead. Revoke access to an externally shared asset leaves members’ permissions unchanged.
  • External access actions undo themselves on failure. Oleria reads every permission it will remove before it changes anything. If a removal fails partway, Oleria grants back what it already removed, restores the repository’s visibility, and the action fails. If a restore also fails, Oleria still tries the others, and the error lists each permission, and the repository visibility, that it couldn’t restore. Check the repository in Bitbucket.
  • A lost reply doesn’t fail a change that was made. If Bitbucket makes a change but its reply is lost, Oleria reads the repository, project, group, or deploy key again. If the change shows, the action succeeds, and you can still revert it.
  • Making a repository private doesn’t remove existing forks. When Revoke access to an externally shared asset makes a repository private, it stops new public forks, but forks that already exist keep their own visibility.
  • Revoke access to an externally shared asset can make no change. When it runs for a repository’s anonymous access and the repository is already private, the action succeeds without changing anything, including the fork setting, and reverting it changes nothing either.
  • Reverting doesn’t downgrade or undo later changes. If the user already has the same or a higher permission when you revert, Oleria leaves it as it is. If someone changed the repository’s visibility or fork setting after Revoke anonymous access or Revoke access to an externally shared asset ran, reverting leaves them as they are and says so. When reverting Remove access for external accounts or Revoke access to an externally shared asset, Oleria skips a repository or project that was deleted. Other reverts fail if the repository or project no longer exists. If a revert restores nothing, its result says so.
  • Group actions change only groups in the connected workspace. Add user to group adds only workspace members, and fails for an external account (a Workspace Collaborator or a non-member). Reverting Remove user from group adds the user back even if they’re a Workspace Collaborator, because it restores their earlier membership. If the user is already in the group (or, for a removal, isn’t in it), the action succeeds without changing anything, and reverting it changes nothing. After each change, Oleria reads the group again, and the action fails if Bitbucket didn’t apply it.
  • Create group fails if the group exists. A group with the same name (ignoring case), or with a name that gives the same Bitbucket group slug, makes the action fail with an error saying the group already exists. For example, Dev Team fails when a group named dev-team exists. Reverting deletes only the group the action created, and only while it has no members.
  • Oleria won’t remove the token owner’s own access, because the integration would lose access to the workspace. This includes removing the token owner from any group, because Bitbucket doesn’t report which group makes them a Workspace Administrator.
  • Disable NHI fails if the key is gone. Oleria reads the repository’s or project’s deploy keys first. If the deploy key, repository, or project no longer exists, the action fails instead of reporting success.
  • Revoke permission works only on user accounts. It can’t remove a deploy key or anonymous access. Use Disable NHI or Revoke anonymous access for those.
  • Revoke anonymous access works only on repositories. If the repository is already private, the action makes no change, and reverting it makes no change either.
  • Reverting may be refused. Bitbucket can refuse to make a repository public again when your workspace settings or the repository’s fork settings don’t allow public repositories. The revert then fails and the repository stays private.
  • Actions stay in the connected workspace. Oleria refuses to change a repository, project, group, or deploy key that belongs to a different Bitbucket workspace, even if the token’s owner administers it.
  • No account or workspace permission changes. Bitbucket’s API can’t remove a member from a workspace or change a workspace permission. To offboard a person, remove them in your Atlassian organization or identity provider.

​
Known limitations

  • No activity. Bitbucket has no audit-log API. See the note under What Oleria discovers for where Bitbucket events come from.
  • No email addresses on accounts. Bitbucket’s API doesn’t return users’ email addresses. Oleria keeps each member’s Atlassian account ID instead, and shows no email for Bitbucket accounts.
  • Group membership may be missing. Bitbucket’s current API (version 2.0) has no endpoint that lists groups or group members. Oleria finds groups from the permissions they hold on projects and repositories, and also tries Bitbucket’s older groups API to read group members and groups without permissions. If Bitbucket refuses that request (for example, because the token doesn’t have admin:workspace:bitbucket, which this API may need), Oleria still shows the groups that hold permissions, their grants, and each member’s effective repository access, but not groups without permissions or who belongs to each group. Only current workspace members are shown as group members. In workspaces that use Atlassian’s centralized user management, group membership is managed in your Atlassian organization, which the Atlassian Cloud integration covers.
  • Rate limits make syncs slow. Bitbucket allows each user about 1,000 API requests per hour. Oleria paces its requests to stay within that limit, so sync time grows with the number of projects and repositories. A workspace with 50 projects and 500 repositories takes about 1.5 hours to sync. Other tools that use the same user’s API tokens share the same limit.
  • Limited MFA and SSO data. Bitbucket’s API doesn’t report two-step verification or single sign-on settings for workspace members. Oleria shows two-step verification status only for the user who owns the API token.
  • Access tokens aren’t discovered. Bitbucket has no API that lists repository, project, or workspace access tokens, so deploy keys are the only non-human identities this integration discovers. Users’ Atlassian API tokens, including the one this integration uses, appear through the Atlassian Cloud integration.
  • Not yet covered. Branch restrictions, Pipelines runners and variables, and webhooks aren’t imported.

​
Contact us

For questions about this integration, contact us at support@oleria.com.