Skip to main content

Bitbucket repository and access

Defines where nullplatform creates Bitbucket Cloud repositories and who gets access to them.

Type: bitbucket

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.

    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.

    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 deployment, which is the service that runs the repository provisioning workflows:

BITBUCKET_EMAIL=np-bot@my-company.com
BITBUCKET_API_TOKEN=ATATT3xFfGF0XXXXXXXXXXXXXXXXXXXXXXXX
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:

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

NameTypeDescriptionRequired
setupobjectThe workspace and project new repositories are created in.
yes
access
(Default Collaborators)		objectPrincipals granted access on every repository nullplatform creates.
no

Additional Properties: not allowed
Example

{
    "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

NameTypeDescriptionRequired
workspace
(Workspace)		stringThe 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)		stringThe 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)		stringBase 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

{
    "workspace": "my-workspace",
    "project_key": "PLAT",
    "installation_url": "https://bitbucket.org"
}

access: Default Collaborators​

Principals granted access on every repository nullplatform creates.

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

NameTypeDescriptionRequired
collaborators
(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

{
    "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

NameTypeDescriptionRequired
id
(ID)		stringThe Atlassian account_id of a workspace member, or the slug of a workspace group.
Minimal Length: 1
yes
role
(Role)		stringThe repository permission granted to the principal.
Enum: "read", "write", "admin"
yes
type
(Type)		stringWhether the principal is an individual user or a workspace group.
Enum: "user", "group"
yes

Item Additional Properties: not allowed
Example

[
    {
        "id": "557058:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "role": "write",
        "type": "user"
    },
    {
        "id": "platform-admins",
        "role": "admin",
        "type": "group"
    }
]