> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket

> Connect a Bitbucket Cloud workspace to Oleria to discover who can reach each project and repository, how they got that access, and which deploy keys and public repositories expose your code.

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](/integrations/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](#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](/integrations/overview#sync-model). When a repository is made private, or a grant is removed in Bitbucket, the access disappears from Oleria on the next sync.

<Note>
  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](/integrations/atlassian-cloud) integration brings them into Oleria. If that integration uses a scoped organization API key, the key needs `read:events:admin`.
</Note>

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

<Warning>
  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.
</Warning>

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

<Steps>
  <Step title="Sign in as the workspace administrator">
    Sign in to [id.atlassian.com](https://id.atlassian.com) as the workspace administrator who will own the token.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    | Scope | Used for |
    | :- | :- |
    | `read:workspace:bitbucket` | Required. The workspace, its members, and their workspace permissions. |
    | `read:user:bitbucket` | Required. Confirms the token works. |
    | `read:project:bitbucket` | Required. Projects and their user and group permissions. |
    | `read:repository:bitbucket` | Required. Repositories, their visibility, and their permissions. |
    | `admin:repository:bitbucket` | Required. Repository deploy keys and repository permissions. Also needed to make a repository private. |
    | `admin:project:bitbucket` | Required. Project deploy keys and project permissions. |
    | `write:permission:bitbucket` | Remediation only. Restores a removed permission when you revert an action, or when an external access action fails partway. |
    | `delete:permission:bitbucket` | Remediation only. Removes a user's direct permission on a repository or project. |
    | `delete:ssh-key:bitbucket` | Remediation only. Deletes a deploy key. |
    | `admin:workspace:bitbucket` | Group actions, and possibly reading group members (see [Known limitations](#known-limitations)). Adds and removes group members and creates groups. See the note on group actions under [Remediation actions](#remediation-actions). |
  </Step>

  <Step title="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.

    <Note>
      Atlassian shows the token value only once, when you create it. Copy it now and store it securely.
    </Note>
  </Step>
</Steps>

<Note>
  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](#verify-the-integration).
</Note>

<Note>
  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.
</Note>

## Connect Bitbucket to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Bitbucket**.
  </Step>

  <Step title="Complete the connection form">
    Fill in the connection form:

    | Field | Notes |
    | :- | :- |
    | Workspace | Required. Your workspace slug - the part after `bitbucket.org/` in your workspace URL. You can't change it after you connect. If you rename the workspace in Bitbucket, the integration keeps working. |
    | Atlassian account email | Optional. The email address of the Atlassian account that owns the API token. Leave it blank to authenticate with the token alone. |
    | API token | Required. The API token you created. Oleria stores it encrypted. |
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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](#known-limitations).

<Note>
  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**.
</Note>

## 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](#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`.

| Action | What it does | Revert |
| :- | :- | :- |
| Revoke permission to a repository or project | Removes a user's direct permission on a repository or project. Group and project access is unchanged, and the result says if the user still has access. | Supported - grants the user the same permission again. |
| Revoke anonymous access | Makes a public repository private. The fork setting is unchanged. To also stop public forks, use **Revoke access to an externally shared asset** for the repository's anonymous access. | Supported - makes the repository public again, unless it's already public or its fork setting changed since. |
| Remove access for external accounts | Removes an external account's direct permission on a repository or project. Oleria runs it once for each repository or project it found the account can reach. If the account reaches the resource only through a group, the action fails, because there's no direct permission to remove. The result says whether the account still has access. | Supported - grants the removed permission again. |
| Revoke access to an externally shared asset | Removes external access to one repository or project. For one external account, it removes that account's direct permission and doesn't change the repository's visibility. For a repository's anonymous access, it only makes the repository private and, if anyone could fork it, allows only private forks. If the repository is already private, it changes nothing. With no account named, it removes every external person's direct permission (app users and teams are left as they are) and, for a repository, also makes it private if it's public and allows only private forks. | Supported - grants the removed permissions again and restores the repository's previous visibility and fork setting. |
| Add user to group | Adds a workspace member to a Bitbucket group. External accounts can't be added. | Supported - removes the user from the group again. |
| Remove user from group | Removes a user from a Bitbucket group. | Supported - adds the user to the group again, if they're still in the workspace. |
| Create group | Creates a Bitbucket group in the workspace. | Supported - deletes the group, but only if it still has no members. |
| Disable NHI | Deletes a repository or project deploy key. Anything that uses the key stops working immediately. | Not supported - Bitbucket can't restore a deleted deploy key. Add a new key instead. |

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.

<Note>
  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.
</Note>

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](#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](/integrations/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](/integrations/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](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.