> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/integrations/bitbucket.md).

# Bitbucket

### Connect Bitbucket Cloud to Upriver with an access token

Upriver supports two Bitbucket Cloud resource access-token options. Choose the option that matches your Bitbucket plan and repository scope:

* **Workspace access token (Bitbucket Cloud Premium):** one token can cover multiple repositories in the same workspace. The token belongs to the workspace rather than to an individual user.
* **Repository access token (no Premium required):** one token can access exactly one repository. To connect multiple repositories this way, create a separate repository access token and a separate Upriver integration for each repository.

Do not use a personal API token created in Atlassian account settings. Personal API tokens use a different authentication scheme and are not supported by this integration. Upriver also does not use OAuth or Forge for this connection.

### Before you start

* Choose a workspace access token or a repository access token.
* Collect the HTTPS URL and default branch for every repository you want Upriver to use.
* Decide the token expiration according to your organization's rotation policy. Bitbucket shows the token value only once.
* For a workspace token, sign in as a workspace administrator. For a repository token, you must be an administrator of the target repository.

### Required permissions

Create either token type with all four permissions below. Upriver's Bitbucket integration is write-capable, so read-only permissions are not sufficient.

* **Repositories — Read:** clone and fetch repository code, branches, commits, and the default branch.
* **Repositories — Write:** push Upriver branches and commits.
* **Pull requests — Read:** read and list pull requests and their context.
* **Pull requests — Write:** create and manage pull requests.

Do not grant Admin, Delete, Pipelines, Webhooks, Runners, or Account permissions unless another application using the same token explicitly needs them. Atlassian recommends single-purpose tokens, so the Upriver token should not be shared with other applications.

### Option 1: Create a workspace access token (Premium)

1. In Bitbucket Cloud, open the workspace that contains the repositories.
2. Select the **Settings** cog, then **Workspace settings**.
3. Under **Security**, select **Access tokens**.
4. Select **Create access token**.
5. Enter a descriptive name such as `upriver-access` and choose an expiration date that follows your organization's rotation policy.
6. Enable **Repositories Read**, **Repositories Write**, **Pull requests Read**, and **Pull requests Write**.
7. Create the token and copy its value immediately. Bitbucket does not display the value again.

### Option 2: Create a repository access token (no Premium required)

1. In Bitbucket Cloud, open the repository you want Upriver to access.
2. Next to the repository name in the left sidebar, select **…**, then **Settings**.
3. Under **Security**, select **Access tokens**.
4. Select **Create access token**.
5. Enter a descriptive name such as `upriver-access` and choose an expiration date.
6. Enable **Repositories Read**, **Repositories Write**, **Pull requests Read**, and **Pull requests Write**.
7. Create the token and copy its value immediately. The token can access only this repository, and Bitbucket does not display its value again.

### Connect Bitbucket in Upriver

1. In Upriver, go to **Settings → Integrations**.
2. Select **Bitbucket** and continue to the configuration step.
3. Optionally enter the token name so administrators can identify the credential later.
4. Paste the access token into the **Workspace access token** field. This field accepts both workspace and repository access tokens.
5. Add at least one repository. Use a URL such as `https://bitbucket.org/my-workspace/my-repository.git` and enter its default branch, for example `main`.
6. If you use a workspace access token, you can add additional repositories from the same workspace. If you use a repository access token, add only the repository that issued that token.
7. Finish creating the integration.

Upriver stores the integration configuration and access token through the normal integration flow, with the token kept as a secret. For Git operations Upriver automatically authenticates with `x-token-auth`; for Bitbucket REST calls it sends the access token as a bearer token. You do not need to configure either authentication detail manually.

### Connect from the Agent integration wizard

You can also create or edit the same native Bitbucket integration from the Agent integration wizard. In the code repository step, select Bitbucket and enter the access token and repository details. Bitbucket always uses the native Access Token path; it does not offer OAuth or Composio as a connection method.

### Bitbucket documentation

* [Create a workspace access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/)
* [Create a repository access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/)
* [Repository access token permissions](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-token-permissions/)