Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

PreviousOpen Metadata

Last updated