--- sidebar_label: Bitbucket repository and access doc_id: 9aa7be63-e712-464b-9b0c-f18bdc96dddb description: >- Configure Bitbucket Cloud repository setup, workspace and project details, and collaborator access permissions. keywords: - Bitbucket - repository configuration - access control - collaborators - API token --- # Bitbucket repository and access Defines where nullplatform creates Bitbucket Cloud repositories and who gets access to them. **Type**: `bitbucket` :::info Bitbucket Cloud only Only **Bitbucket Cloud** is supported. Bitbucket **Data Center** uses a different API and has no Pipelines product, so it cannot act as a code-repository or CI provider. ::: ## Before you begin Bitbucket integration authenticates as a **dedicated bot user** (a service account, not a person) using an **Atlassian API token**. Set this up before creating the provider configuration: 1. **Create a dedicated Bitbucket bot user.** Use a service account rather than an employee's personal login, so the integration survives staff changes. On the Free plan this bot consumes one of the workspace seats. 2. **Enable two-step verification on the bot's _Bitbucket_ account.** Bitbucket requires a two-step-verified **user** principal to enable Pipelines. There is no way around it, and an OAuth app can never satisfy this check. :::warning Bitbucket 2SV is not Atlassian-account 2FA Two-step verification must be enabled on the **Bitbucket** account, **not** on the Atlassian account. Enabling two-factor authentication on the Atlassian account does **not** satisfy this requirement, and Pipelines will stay disabled through both the UI and the API until Bitbucket 2SV is on. This is the single most common onboarding mistake. ::: 3. **Issue an Atlassian API token scoped to Bitbucket.** REST calls authenticate with HTTP Basic auth using `email:api_token`. Git-over-HTTPS uses the literal username `x-bitbucket-api-token-auth`. :::danger App passwords are not supported Atlassian removed Bitbucket **app passwords** on **2026-07-28**. Do not use them anywhere, the integration only supports Atlassian API tokens. ::: ### Credentials live outside this configuration The bot's credentials are **not** part of the provider configuration. Set them as environment variables on your [application-lifecycle-manager](https://github.com/nullplatform/application-lifecycle-manager) deployment, which is the service that runs the repository provisioning workflows: ```bash BITBUCKET_EMAIL=np-bot@my-company.com BITBUCKET_API_TOKEN=ATATT3xFfGF0XXXXXXXXXXXXXXXXXXXXXXXX ``` :::note Token rotation Atlassian API tokens expire after at most **365 days**. Rotate the token before it expires and update `BITBUCKET_API_TOKEN`, or provisioning will start failing with `401`. ::: ### Required API token scopes Grant the bot token **all** of the scopes below. Bitbucket's granular scopes are independent, not hierarchical. An `admin:` scope does **not** imply the matching `write:` scope, so each must be granted explicitly: ```text admin:repository:bitbucket write:repository:bitbucket read:repository:bitbucket admin:pipeline:bitbucket write:pipeline:bitbucket read:pipeline:bitbucket admin:project:bitbucket read:project:bitbucket write:webhook:bitbucket read:webhook:bitbucket read:workspace:bitbucket write:permission:bitbucket read:permission:bitbucket ``` **Properties** |Name|Type|Description|Required| |----|----|-----------|--------| |[**setup**](#setup)|`object`|The workspace and project new repositories are created in.
|yes| |[**access**](#access)
(Default Collaborators)|`object`|Principals granted access on every repository nullplatform creates.
|no| **Additional Properties:** not allowed **Example** ```json { "setup": { "workspace": "my-workspace", "project_key": "PLAT", "installation_url": "https://bitbucket.org" }, "access": { "collaborators": [ { "id": "557058:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "role": "write", "type": "user" }, { "id": "platform-admins", "role": "admin", "type": "group" } ] } } ``` ## setup: Setup The workspace and project new repositories are created in. **Properties** |Name|Type|Description|Required| |----|----|-----------|--------| |**workspace**
(Workspace)|`string`|The Bitbucket workspace ID: the `{workspace}` segment of `https://bitbucket.org/{workspace}/{repository}`. Repositories are created inside it.
Minimal Length: `2`
Maximal Length: `63`
|yes| |**project\_key**
(Project Key)|`string`|The key of the Bitbucket project that owns new repositories.
Minimal Length: `1`
Maximal Length: `64`
Pattern: `^[A-Z][A-Z0-9_]{0,63}$`
|yes| |**installation\_url**
(Installation URL)|`string`|Base URL of the Bitbucket installation, with no trailing slash. Keep the default for Bitbucket Cloud.
Pattern: `^https://[^/]+$`
Default: `"https://bitbucket.org"`
|no| **Additional Properties:** not allowed **Example** ```json { "workspace": "my-workspace", "project_key": "PLAT", "installation_url": "https://bitbucket.org" } ``` ## access: Default Collaborators Principals granted access on every repository nullplatform creates. :::note Collaborators must already be workspace members Bitbucket has no API to invite a user into a workspace. Every principal listed here must **already** be a member of the workspace. Nullplatform can grant repository permissions to existing members, but it cannot add new ones. If a principal is not a workspace member, the grant fails with a clear error naming the missing member. ::: **Properties** |Name|Type|Description|Required| |----|----|-----------|--------| |[**collaborators**](#accesscollaborators)
(Default Collaborators)|`object[]`|Users and groups granted permission on every new repository. They must already be members of the workspace.
|no| **Additional Properties:** not allowed **Example** ```json { "collaborators": [ { "id": "557058:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "role": "write", "type": "user" }, { "id": "platform-admins", "role": "admin", "type": "group" } ] } ``` ### access\.collaborators\[\]: Default Collaborators Users and groups granted permission on every new repository. They must already be members of the workspace. **Items** **Item Properties** |Name|Type|Description|Required| |----|----|-----------|--------| |**id**
(ID)|`string`|The Atlassian `account_id` of a workspace member, or the slug of a workspace group.
Minimal Length: `1`
|yes| |**role**
(Role)|`string`|The repository permission granted to the principal.
Enum: `"read"`, `"write"`, `"admin"`
|yes| |**type**
(Type)|`string`|Whether the principal is an individual user or a workspace group.
Enum: `"user"`, `"group"`
|yes| **Item Additional Properties:** not allowed **Example** ```json [ { "id": "557058:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "role": "write", "type": "user" }, { "id": "platform-admins", "role": "admin", "type": "group" } ] ```