Bitbucket

What your agents can doCopy Anchor Link

Helios indexes the Bitbucket Cloud REST API, so agents search it at run time and call the endpoints the credential allows. The credential is attached server-side.

• Open pull requests, and review, comment on, approve, decline, or merge them
• Read diffs, commits, branches, and files at any ref
• Check build statuses and Bitbucket Pipelines runs, steps, and logs, and run or stop pipelines
• Create branches and tags, and report build statuses
• With admin permissions, manage repository and project settings, branch restrictions, default reviewers, and Pipelines variables

Agents can send JSON and multipart request bodies, including file uploads. Bitbucket removed its issue tracker and wikis on August 20, 2026, so there are no issue or wiki endpoints or events.

AuthenticationCopy Anchor Link

Every method asks for two more fields:

• Workspace ID is the first part of your Bitbucket URLs, as in bitbucket.org/<workspace ID>.
• Repository is optional. Leave it empty to use the whole workspace. To use one repository, enter its slug, as in bitbucket.org/<workspace ID>/<repository slug>. Helios then tests the connection against that repository and registers the webhook there. Project and repository access tokens need it to connect.

Bitbucket stopped accepting app passwords on July 28, 2026, so Helios does not offer them. See Integration authentication for how credentials are stored and injected.

Each method below lists the permissions for full access, and names the ones Helios itself needs after the table. Permissions marked admin grant administration rights, such as editing branch restrictions or deleting projects. An API token or OAuth app only gets them where its account is an admin.

Atlassian API TokenCopy Anchor Link

You need a Bitbucket account in the workspace. For triggers with Repository empty, the account must be a workspace admin. With Repository set, it must be an admin of that repository.

1. In Bitbucket, select your avatar, then Account settings, and open the Security tab.
2. Select Create and manage API tokens, then Create API token with scopes.
3. Enter a name and an expiry date, and select Next. Choose Bitbucket as the app, and select Next.
4. Select the scopes below, then select Next and Create token. Copy the token.
5. In Helios, choose Atlassian API Token. Enter the token in API Token, your Atlassian account's email in Atlassian Account Email, and the workspace in Workspace ID. Optional: enter a repository slug in Repository.
6. Save.

Helios itself uses read:workspace:bitbucket to test the connection when Repository is empty, and read:repository:bitbucket when it is set. It uses the three webhook scopes to register and remove the Helios webhook. The pull request, pipeline, and project events also need read:pullrequest:bitbucket, read:pipeline:bitbucket, and read:project:bitbucket.

An API token expires after at most one year, and its scopes can't be changed. Before it expires, or to add scopes, create a new token and enter it through Manage. Bitbucket records every change made with the token as the account that owns it.

Bitbucket Access TokenCopy Anchor Link

Repository access tokens work on every plan. Workspace and project access tokens need Bitbucket Premium.

1. Open the settings for the token's scope:
   • Repository: select More actions (…) next to the repository name, then Settings → Security → Access tokens.
   • Project: select More actions (…) on the project, then Settings → Security → Access tokens.
   • Workspace: select the settings cog, then Workspace settings → Security → Access tokens.
2. Select Create access token, enter a name, and choose an expiry.
3. Select every permission below that the token type offers. Then create the token and copy it.
4. In Helios, choose Bitbucket Access Token. Enter the token in Access Token and the workspace in Workspace ID.
5. For a project or repository access token, enter a repository slug in Repository. These tokens only reach their own project or repository, and without it Helios tests the connection against the whole workspace.
6. Save.

Helios itself needs Repositories Read and Webhooks Read and write. The pull request and pipeline events also need Pull requests Read and Pipelines Read, and the project event needs Projects Read.

Bitbucket's docs don't say whether a workspace access token can register a workspace webhook. If no webhook appears, set Repository to register it on one repository. Access token permissions can't be changed after creation. If the token has an expiry date, or you need more permissions, create a new token and enter it through Manage.

Your own Bitbucket OAuth appCopy Anchor Link

You need to be a workspace admin to add an OAuth consumer.

1. In Bitbucket, select the settings cog, then Workspace settings → Apps and features → OAuth consumers, and select Add consumer.

2. Enter a Name, and set Callback URL to:

   Copy Text

   https://api.heliosapp.com/integrations/bitbucket/oauth_callback

3. Under Permissions, select every permission below.

4. Select Save. Select the consumer's name to show its Key and Secret.

5. In Helios, choose Your own Bitbucket OAuth app. Enter the key in OAuth Consumer Key, the secret in OAuth Consumer Secret, and the workspace in Workspace ID. Optional: enter a repository slug in Repository.

6. Save, then approve access in Bitbucket.

Helios itself needs Repositories Read and Webhooks Read and write. The pull request and pipeline events also need Pull requests Read and Pipelines Read, and the project event needs Projects Read.

Helios doesn't ask for scopes, and there is no Admin access option for this method. Bitbucket gives every token exactly the permissions set on the consumer, so change them there, then click Re-connect. Agents act as the person who approved access, and the admin permissions only work where that person is an admin. For a workspace webhook, that person must be a workspace admin. Otherwise, set Repository to a repository they administer.

Helios renews access tokens with the refresh token. A refresh token that isn't used for three months expires. If that happens, open the connection and click Re-connect.

TriggersCopy Anchor Link

Bitbucket can start a Workflow when something happens in your repositories. Helios registers a webhook titled Helios when you save the connection, so there is nothing to paste into Bitbucket. The webhook subscribes to the events below that its credentials and repository setting allow. Deleting the connection removes the webhook.

• With Repository empty, Helios registers one workspace webhook. It covers every repository in the workspace, including ones created later. Bitbucket only lets workspace admins create workspace webhooks.
• With Repository set, Helios registers the webhook on that repository only. This needs admin access to the repository. Bitbucket sends repository.created, repository.imported, repository.transferred, repository.deleted, and project.updated only to workspace webhooks, so the trigger picker shows them as unavailable.

Bitbucket only lets a webhook subscribe to an event when the credential can read what the event is about. If the credential lacks Pull requests Read, Pipelines Read, or Projects Read, Helios subscribes to the other events and the trigger picker shows the refused ones as unavailable. Add the permission, or create a new token with it, and save the connection again.

Setting Repository on a connection that had a workspace webhook removes that webhook. Any other change to Workspace ID or Repository on a saved connection leaves the old webhook in Bitbucket. Create a new connection and delete the old one instead.

Every filter is optional. Patterns are case-sensitive.

• Repository lists the workspace's repositories, or only the one set on the connection. Choose one or more. An event without a repository, such as project.updated, never matches it.
• Destination branch matches the branch a pull request merges into, such as main or release/*.
• Branch matches any branch a push created, updated, or deleted, the branch a build ran on, or the branch a pipeline ran on. A build status that doesn't name a branch never matches it.
• Tag matches any tag a push created, moved, or deleted, such as v*.
• Build state is one or more of Successful, Failed, In progress, and Stopped.
• Build name matches the build's name, such as Unit tests*.
• Span name matches the name of a trace span, such as bbc.pipeline_run.

Some notes on specific events:

• Bitbucket Pipelines reports a build as In progress first, then updates it. For failed Pipelines builds, use build_status.updated with Build state set to Failed. A build system that reports a failed status straight away sends build_status.created instead.
• A finished Pipelines run sends spans for the run and for its steps, containers, and logs. Set Span name to bbc.pipeline_run to start one run for each pipeline run.
• repository.deleted arrives when Bitbucket permanently deletes the repository, which can be up to 30 days after someone deletes it.
• New commits on a pull request's branch arrive as pull_request.updated, whether they were pushed with git or committed through the API. Helios does not offer the separate pull request push event.
• A comment edited through the API may not send pull_request_comment.updated.

Deliveries are verified with the HMAC-SHA256 X-Hub-Signature header. Bitbucket sends no delivery timestamp, so Helios drops repeated deliveries by their X-Request-UUID instead. Bitbucket sends a delivery again, up to two more times, when Helios answers with a server error.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Bitbucket rejected the credential or couldn't find the workspace or repository. Click Test Connection to check again.
• The webhook: for a repository webhook, select More actions (…) next to the repository name, then Settings, then Webhooks under Workflow. A webhook titled Helios should be listed. View requests shows its deliveries after you select Enable history. Bitbucket's docs describe no page that lists workspace webhooks, so check a workspace webhook with a test event.
• A trigger:
  1. Add pull_request.created to a workflow with no filters.
  2. Open a test pull request.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Bitbucket Cloud counts authenticated requests per user over a rolling hour. Most repository data allows 1,000 requests an hour, and webhook calls allow 1,000 an hour. Requests over a limit get 429 Too Many Requests. See Bitbucket's API request limits. A repository can have up to 50 webhooks.

Workspaces on the Free plan can't use snippets or the repository's Downloads section, and Bitbucket answers those calls with 402 Payment Required. They need the Standard or Premium plan. See changes to Bitbucket Cloud's free plan.