# Bitbucket
Connecting Bitbucket gives SureCloud read access to your Bitbucket workspace's repositories, branch permissions, pull request policies, and user and group access configuration. SureCloud monitors branch restriction rules to verify that direct pushes to default branches are prevented and that pull request approvals are enforced, audits repository access to identify repositories with public visibility or overly broad user permissions, and enumerates workspace members to detect inactive accounts. This provides continuous evidence that your source code management environment enforces peer review and access governance controls.
{% hint style="info" %}
SureCloud connects to Bitbucket Cloud using OAuth 2.0. For Bitbucket Data Center (self-hosted), a Personal Access Token is used instead. No credentials are stored for Cloud connections — access is maintained via a refresh token that SureCloud rotates automatically.
{% endhint %}
## Authentication and setup
{% tabs %}
{% tab title="Bitbucket Cloud (OAuth 2.0)" %}
{% stepper %}
{% step %}
#### Initiate the connection in SureCloud
In SureCloud, navigate to **Integrations → Bitbucket → Connect**. SureCloud redirects you to Bitbucket's OAuth authorisation page.
{% endstep %}
{% step %}
#### Authorise SureCloud in Bitbucket
Review the requested permissions and click **Grant access**. The OAuth app is pre-registered by SureCloud.
SureCloud requests the following OAuth scopes:
| Scope | Purpose |
| ------------- | ------------------------------------------------------------------ |
| `account` | Read the authorising user's account and workspace memberships |
| `repository` | Read repository metadata, access settings, and branch restrictions |
| `team` | Read workspace (team) membership and group configuration |
| `pullrequest` | Read pull request settings and approval history |
{% hint style="warning" %}
The authorising account must be a **workspace administrator** to read workspace-level member lists and group assignments. Member accounts can only read repositories they have explicit access to.
{% endhint %}
{% endstep %}
{% step %}
#### Select workspaces to monitor
After authorisation, return to SureCloud and select the Bitbucket workspaces you want to monitor. If the authorising account belongs to multiple workspaces, each can be added individually.
Click **Save Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% tab title="Bitbucket Data Center (Personal Access Token)" %}
{% stepper %}
{% step %}
#### Create a dedicated service account
In your Bitbucket Data Center instance, create a service account user (e.g. `surecloud-ccm`). Grant the account **Read** access to all projects and repositories you want SureCloud to monitor. The account does not need admin rights unless workspace-level membership data is required.
For project-level membership and permission scheme data, the account must have the **Project Administrator** role on each target project.
{% endstep %}
{% step %}
#### Generate a Personal Access Token
Log in as the `surecloud-ccm` account and navigate to **Profile → Personal Access Tokens → Create token**.
* **Name**: `SureCloud CCM`
* **Permissions**: Repositories — Read; Projects — Read
* **Expiry**: set a date and record a reminder to rotate before expiry
Copy the token value immediately.
{% hint style="warning" %}
Rotate this token before its expiry date and update the value in **SureCloud → Integrations → Bitbucket → Edit Connection** to avoid a data collection gap.
{% endhint %}
{% endstep %}
{% step %}
#### Enter credentials in SureCloud
In SureCloud, navigate to **Integrations → Bitbucket → Connect (Data Center)** and provide:
* **Bitbucket Data Center base URL** (e.g. `https://bitbucket.yourcompany.com`)
* **Personal Access Token**
Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}
## Endpoints
| API Call | Use Case |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET /2.0/workspaces/{workspace}/members` | Enumerate workspace members; detect inactive or external accounts |
| `GET /2.0/workspaces/{workspace}/permissions` | Read workspace-level permission assignments |
| `GET /2.0/repositories/{workspace}` | List all repositories in the workspace; detect public repositories |
| `GET /2.0/repositories/{workspace}/{repo_slug}` | Read repository access level (public/private) and fork policy |
| `GET /2.0/repositories/{workspace}/{repo_slug}/branch-restrictions` | Read branch restriction rules; verify push and merge restrictions on default branches |
| `GET /2.0/repositories/{workspace}/{repo_slug}/permissions-config/users` | Read per-user repository permission assignments |
| `GET /2.0/repositories/{workspace}/{repo_slug}/permissions-config/groups` | Read group-level repository permission assignments |
| `GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests` | Read recent pull request records; verify approval requirements are being met |
| `GET /2.0/workspaces/{workspace}/projects` | Enumerate projects and their default branch configuration |
## Pagination
The Bitbucket Cloud REST API uses page-based pagination via a `next` URL in the response body. SureCloud follows the `next` URL in each response until no `next` field is present.
```json
{
"pagelen": 100,
"size": 847,
"page": 1,
"next": "https://api.bitbucket.org/2.0/repositories/myworkspace?page=2",
"values": [
{ "slug": "backend-api", "is_private": true, "full_name": "myworkspace/backend-api", ... }
]
}
```
SureCloud requests up to 100 results per page using `pagelen=100`.
## Required permissions
For Bitbucket Cloud (OAuth), the authorising account must be a **workspace administrator** for SureCloud to read workspace membership and group assignments. Repository-level data is accessible to any account with Read access to those repositories.
For Bitbucket Data Center (Personal Access Token), the service account must have:
| Permission | Scope |
| -------------------------------- | -------------------------------------------------- |
| Read | All target repositories |
| Project Read | All target projects |
| Project Administrator (optional) | Required only for permission scheme and group data |
## Polling frequency
| Data type | Collection interval |
| -------------------------------------------- | ------------------- |
| Repository inventory and visibility settings | 24 hours |
| Branch restriction rules | 24 hours |
| Workspace and repository membership | 24 hours |
| Pull request approval records | 6 hours |
## Troubleshooting
Branch restriction rules are returning as empty for repositories that have restrictions configured
Branch restriction rules are accessible to workspace administrators and repository administrators. If the authorising account (OAuth) or service account (PAT) does not have administrator access to a repository, the `branch-restrictions` endpoint will return an empty list rather than a permission error.
Confirm the SureCloud-connected account has at least **Admin** access to the repositories you expect to see restrictions for, or ensure the account is a workspace administrator which grants implicit access to all repository settings.
Public repositories are not being flagged by SureCloud
SureCloud reads the `is_private` field on each repository. A value of `false` indicates the repository is publicly accessible. If public repositories are not appearing as findings, confirm SureCloud has enumerated all repositories in the workspace by checking the total repository count in **SureCloud → Integrations → Bitbucket**.
If the count is lower than expected, the OAuth authorising account may not have access to all repositories. Workspace administrators have visibility into all repositories regardless of individual access grants.
Workspace members are not appearing for some workspaces
Workspace membership data is accessible only to workspace administrators. If the account that authorised the OAuth connection is a member (not an admin) of a workspace, the `/workspaces/{workspace}/members` endpoint will return a 403 error.
Re-connect the integration using a workspace administrator account via **SureCloud → Integrations → Bitbucket → Reconnect**.
OAuth token has expired and the connection is failing
SureCloud maintains the connection using a refresh token. Bitbucket Cloud refresh tokens do not expire unless explicitly revoked. If the connection is failing with an authentication error, the OAuth app access may have been revoked by a workspace administrator.
In Bitbucket Cloud, navigate to **Personal settings → Apps and features → Authorised applications** and confirm the SureCloud OAuth app is still listed. If it has been revoked, re-connect via **SureCloud → Integrations → Bitbucket → Reconnect**.
Bitbucket Cloud REST API reference Bitbucket Data Center REST API reference
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/bitbucket.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.