Menu

Mattering Automations Bitbucket integration

Connect Bitbucket to Mattering Automations: workspaces, repositories, branches and tags, commits with diffs, the full pull request lifecycle, issues, Pipelines, source browsing, and webhook management as workflow steps, authenticated with an Atlassian account email and a scoped API token.

The Mattering Automations Bitbucket integration adds the Bitbucket Cloud REST API 2.0 to your automation canvas: list workspaces and their members, create and update repositories, work branches, tags, and commits with raw diffs and per-file diffstats, run the whole pull request lifecycle from opening through inline comments, approvals, and the merge, triage the repository issue tracker, trigger and watch Bitbucket Pipelines, browse source, and manage webhook subscriptions.

Start with the credential, because it changed. Bitbucket app passwords were permanently removed by Atlassian on 2026-07-28, so the credential here is a scoped Atlassian API token created at id.atlassian.com: your Atlassian account email is the basic auth username and the token is the password. Setup takes a few minutes once you have the token, and this guide walks through each step and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 49 nodes, 30 read and 19 act, and four of those carry a destructive flag: Bitbucket: Delete Branch, Bitbucket: Merge Pull Request, Bitbucket: Decline Pull Request, and Bitbucket: Delete Webhook. Repository deletion is deliberately not a node at all, because deleting a Bitbucket Cloud repository is permanent and takes the git history, issues, and pull requests with it. Bitbucket: Run Pipeline is not destructive, but it spends build minutes, which are a metered paid resource on your Bitbucket plan.

Before you start

  • A Bitbucket Cloud account with access to the workspaces and repositories you want to automate. The free plan is enough to build and test a workflow end to end: it includes full REST API access, API tokens, private repositories, and 50 Pipelines build minutes per month.
  • An Atlassian account you can sign in to at id.atlassian.com, because the credential is created in Atlassian account settings rather than anywhere inside the Bitbucket interface.
  • A Mattering workspace with access to the Automations app.
  • For the issue nodes, a repository with its issue tracker switched on under Repository settings, then Features. It is off by default on a new repository, and every issue node returns 404 until it is enabled.

Create a scoped Atlassian API token

Mattering authenticates to Bitbucket with HTTP basic auth, where the username is your Atlassian account email and the password is a scoped Atlassian API token. App passwords, the credential most Bitbucket automation guides still describe, no longer exist: Atlassian ran a staged deprecation through 2025 and 2026 and removed them permanently on 2026-07-28. There is no compatibility mode, so an old app password is not a weaker credential, it is a dead one.

Sign in at id.atlassian.com and open Security, then API tokens (id.atlassian.com/manage-profile/security/api-tokens).
Create an API token with scopes. A plain unscoped token is meant for other Atlassian products; the Bitbucket REST API needs the scoped kind.
Select the Bitbucket scopes your automations actually need, for example read:repository:bitbucket for a read-only workflow and write:repository:bitbucket when the workflow also opens pull requests, comments, or merges.
Choose an expiry date, create the token, and copy the value straight away. Atlassian shows it once.
If you already have a Bitbucket app password saved somewhere, it will not work. Atlassian removed app passwords permanently on 2026-07-28, and requests using one now come back as a plain 401 that reads exactly like a mistyped token. Create an API token instead; that 401 is the single most common reason this connector appears broken on first setup.
The username is your Atlassian account email, not your Bitbucket username. The static x-bitbucket-api-token-auth username you may have seen in Atlassian's git documentation is a git-over-HTTPS transport detail and does not apply to REST API calls or to this connector.
Atlassian API tokens expire on the date you pick at creation and cannot be refreshed, only replaced. Note the date somewhere the team will see it: a workflow that has run cleanly for months will start returning 401s on every node the day the token lapses.

Connect Bitbucket to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Bitbucket from the list.
Click Create new credential, enter your Atlassian account email as the username and the API token as the password, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering calls Bitbucket's authenticated user endpoint and confirms the pair authenticates. A 200 proves the connection; a 401 means the email, the token, or the credential class is wrong.
Click Connect. All 49 Bitbucket nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Bitbucket section should list the query and action nodes. Drop Bitbucket: Get Current User onto the canvas and run a test step. It takes no parameters and is the connector's auth probe, so a successful response returns the display name, nickname, and account id of the account the token belongs to and proves the email and token pair is right. Nothing sensitive comes back in it: Bitbucket does not echo the token, the password, or an email address on that endpoint.

Next, run Bitbucket: List Workspaces. Almost every other node needs the workspace slug it returns, so copy one and keep it handy, then run Bitbucket: List Repositories for that workspace to confirm repository-level access. Everything in this verify path is read-only: it cannot reach the four destructive nodes and it cannot spend build minutes, so it is safe to re-run whenever you rotate the token.

Node reference

49 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 30

Bitbucket: Browse Source

bitbucket_browse_source

List a directory in the repository at a given revision (leave path blank for the repository root): entries come back as commit_file and commit_directory objects with paths and sizes. For a FILE path, set format to meta to get its metadata as JSON; raw file text belongs to the Get File Content node.

Bitbucket: Compare Commits (Diff)

bitbucket_get_diff

Return the unified diff between two commits as raw text (data.content), capped at 200,000 characters with a truncation flag. Ideal for feeding a code change to an AI node. Defaults to a three-dot diff (source against the merge base); set topic false for a plain two-dot diff.

Bitbucket: Compare Commits (Diffstat)

bitbucket_get_diffstat

Summarize the change between two commits per file: status (added, removed, modified, renamed), lines added, and lines removed. The bounded JSON alternative to the raw diff.

Bitbucket: Get Branch

bitbucket_get_branch

Fetch one branch by name, including its head commit and the merge strategies configured for it. Branch names with slashes (feature/login) are URL-encoded for you.

Bitbucket: Get Commit

bitbucket_get_commit

Fetch one commit by hash: message, author, date, and parents. Note the path segment is commit (singular), unlike the commits list; that is Bitbucket's own naming.

Bitbucket: Get Current User

bitbucket_get_current_user

Return the authenticated Bitbucket account: display name, nickname, account_id, and uuid. Zero-parameter Safe Read, so it doubles as the credential health check: 401 means the email or API token is wrong, 200 proves the connection.

Bitbucket: Get File Content

bitbucket_get_file_content

Fetch the raw contents of one TEXT file at a revision into data.content, capped at 200,000 characters with a truncation flag. Binary files decode to garbage (check the size and type with Browse Source first) and files stored in Git LFS return a redirect instead of content.

Bitbucket: Get Issue

bitbucket_get_issue

Fetch one issue: title, state, kind, priority, assignee, and content. Requires the repository's issue tracker to be enabled (Repository settings > Features); a repo without it returns 404.

Bitbucket: Get Pipeline

bitbucket_get_pipeline

Fetch one pipeline run: state, result, target ref and commit, trigger, and build seconds used. Poll this after Run Pipeline to watch a build finish.

Bitbucket: Get Pull Request

bitbucket_get_pull_request

Fetch one pull request: title, state, source and destination branches, reviewers, participants with approval state, and counts.

Bitbucket: Get Pull Request Diffstat

bitbucket_get_pull_request_diffstat

Per-file change summary for a pull request: status, lines added, lines removed. The bounded way to see what a pull request touches.

Bitbucket: Get Repository

bitbucket_get_repository

Fetch one repository: full_name, main branch, language, size, privacy, project, and clone links.

Bitbucket: Get Tag

bitbucket_get_tag

Fetch one tag by name, including its target commit, tagger, and message.

Bitbucket: Get Workspace

bitbucket_get_workspace

Fetch one workspace by slug or UUID: name, slug, privacy settings, forking mode, and links.

Bitbucket: List Branches

bitbucket_list_branches

List open branches in a repository, each with its head commit. Sorting by name uses natural sort order.

Bitbucket: List Commits

bitbucket_list_commits

List commits in reverse chronological order, like git log. Filter the DAG with include and exclude refs and narrow to commits touching a file or directory with path. This endpoint paginates by opaque cursors, not page numbers: to get the next page, call again with the URL from data.next (or raise pagelen).

Bitbucket: List Deployments

bitbucket_list_deployments

List Bitbucket Pipelines deployments for a repository: which release went to which environment, with state and commit.

Bitbucket: List Environments

bitbucket_list_environments

List the deployment environments configured for a repository (for example Test, Staging, Production) with their UUIDs.

Bitbucket: List Issue Comments

bitbucket_list_issue_comments

List comments on an issue, oldest first. Requires the repository's issue tracker to be enabled (Repository settings > Features); a repo without it returns 404.

Bitbucket: List Issues

bitbucket_list_issues

List issues in the repository's issue tracker, filterable by state, kind, priority, and assignee via the q field. Requires the repository's issue tracker to be enabled (Repository settings > Features); a repo without it returns 404.

Bitbucket: List Pipelines

bitbucket_list_pipelines

List pipeline runs for a repository, filterable by status, target branch, and trigger type. Sort by -created_on for newest first.

Bitbucket: List Pull Request Activity

bitbucket_list_pull_request_activity

The audit trail of a pull request: updates, approvals, change requests, and comments, newest first. Each value has one of an update, approval, changes_requested, or comment key. This endpoint paginates by opaque cursors, not page numbers: to get the next page, call again with the URL from data.next (or raise pagelen).

Bitbucket: List Pull Request Comments

bitbucket_list_pull_request_comments

List comments on a pull request, both general and inline (inline ones carry the file path and line).

Bitbucket: List Pull Request Commits

bitbucket_list_pull_request_commits

List the commits a pull request would merge, newest first. This endpoint paginates by opaque cursors, not page numbers: to get the next page, call again with the URL from data.next (or raise pagelen).

Bitbucket: List Pull Requests

bitbucket_list_pull_requests

List pull requests, filterable by state (OPEN, MERGED, DECLINED, SUPERSEDED) and by query expressions. Defaults to open pull requests when no state is given.

Bitbucket: List Repositories

bitbucket_list_repositories

List repositories in a workspace, filterable by the authenticated user's role and by Bitbucket query expressions (name, language, updated_on and more).

Bitbucket: List Tags

bitbucket_list_tags

List tags in a repository, each with its target commit and tag message.

Bitbucket: List Webhooks

bitbucket_list_webhooks

List webhook subscriptions on a repository: target URL, subscribed events, active flag, and whether a signing secret is set (the secret itself is never echoed).

Bitbucket: List Workspace Members

bitbucket_list_workspace_members

List all members of a workspace as user objects. Workspace administrators can additionally filter by email address with the q field.

Bitbucket: List Workspaces

bitbucket_list_workspaces

List every workspace the authenticated user can access, each with an administrator flag saying whether the user is a workspace admin. Uses the supported /2.0/user/workspaces endpoint (the old /2.0/workspaces list is deprecated by Atlassian).

Action nodes 19

Bitbucket: Approve Pull Request

bitbucket_approve_pull_request

Approve a pull request as the authenticated user. Reversed by the Unapprove node.

Bitbucket: Create Branch

bitbucket_create_branch

Create a branch pointing at a commit. The vendor docs recommend a full commit hash as the target; a branch name or an unambiguous short hash also works (an ambiguous prefix returns 400).

Bitbucket: Create Issue

bitbucket_create_issue

Create an issue in the repository's issue tracker. Only title is required. Requires the repository's issue tracker to be enabled (Repository settings > Features); a repo without it returns 404.

Bitbucket: Create Issue Comment

bitbucket_create_issue_comment

Comment on an issue as the authenticated user. Requires the repository's issue tracker to be enabled (Repository settings > Features); a repo without it returns 404.

Bitbucket: Create Pull Request

bitbucket_create_pull_request

Open a pull request from a source branch. Destination defaults to the repository's main branch when left blank. The authenticated user becomes the author.

Bitbucket: Create Pull Request Comment

bitbucket_create_pull_request_comment

Comment on a pull request. Fill inline_path (and optionally inline_line) to attach the comment to a specific file and line of the diff; leave both blank for a general comment.

Bitbucket: Create Repository

bitbucket_create_repository

Create a git repository in a workspace. The repo_slug in the URL becomes the repository's slug. On workspaces that require projects, set project_key or Bitbucket assigns the oldest project automatically.

Bitbucket: Create Webhook

bitbucket_create_webhook

Subscribe a URL to repository events (repo:push, pullrequest:created, and more). When a secret is set, Bitbucket signs each delivery with an HMAC digest in the X-Hub-Signature header. The URL must be publicly routable.

Bitbucket: Decline Pull Request

bitbucket_decline_pull_request

DESTRUCTIVE: decline (reject) a pull request. The record survives, but a declined pull request cannot be reopened on Bitbucket Cloud; the recovery path is opening a new pull request from the same branches. No code is changed.

Bitbucket: Delete Branch

bitbucket_delete_branch

DESTRUCTIVE: delete a branch. Commits only reachable from this branch become unreferenced and are eventually garbage collected; there is no undelete. Recreate the branch from its old head hash immediately if this was a mistake.

Bitbucket: Delete Webhook

bitbucket_delete_webhook

DESTRUCTIVE: delete a webhook subscription. Deliveries stop immediately and the subscription cannot be restored; it must be recreated (and a signing secret re-entered) if removed by mistake.

Bitbucket: Merge Pull Request

bitbucket_merge_pull_request

DESTRUCTIVE-ADJACENT: merge a pull request into its destination branch. This changes real code state; the only undo is new revert commits. Runs synchronously (long merges can time out server-side; Bitbucket's async mode is not exposed here).

Bitbucket: Request Changes on Pull Request

bitbucket_request_changes_pull_request

Mark a pull request as changes requested by the authenticated user. The matching remove endpoint is not built; approving the pull request supersedes the request in practice.

Bitbucket: Run Pipeline

bitbucket_run_pipeline

COSTS BUILD MINUTES: trigger a Bitbucket Pipelines run on a branch or tag. Build minutes are a metered, paid resource on the workspace's plan, so treat this like a spend action. Set selector_type custom plus selector_pattern to run a custom pipeline; add variables for parameterized runs. Stop Pipeline cancels a run in progress.

Bitbucket: Stop Pipeline

bitbucket_stop_pipeline

Stop (halt) a pipeline that is pending or in progress. Stops billing for the run; the pipeline shows as stopped. Returns 204 with no body.

Bitbucket: Unapprove Pull Request

bitbucket_unapprove_pull_request

Withdraw the authenticated user's own approval from a pull request. Returns 204 with no body.

Bitbucket: Update Issue

bitbucket_update_issue

Edit an issue: title, body, kind, priority, workflow state, or assignee. Fields left blank keep their current value; to clear a field, send null for it via extra_body. Requires the repository's issue tracker to be enabled (Repository settings > Features); a repo without it returns 404.

Bitbucket: Update Pull Request

bitbucket_update_pull_request

Edit an open pull request: title, description, destination branch, draft flag, or the reviewer list. Only open pull requests can be edited. Fields left blank are not touched, but note a reviewers value REPLACES the whole reviewer list.

Bitbucket: Update Repository

bitbucket_update_repository

Update repository settings: description, privacy, language, issue tracker and wiki toggles, fork policy, or project. Careful with name: renaming a repository also changes its slug, which breaks existing clone URLs and any automations pointing at the old slug. Fields left blank are not touched.

Using the integration

On the automation canvas

Bitbucket nodes chain with every other node: a scheduled Bitbucket: List Pull Requests sweep can open review tasks in Mattering Productivity for anything sitting without reviewer activity, a failed run found by Bitbucket: List Pipelines can post a message with the failing branch, and Bitbucket: List Issues can feed triage into a Mattering database next to the rest of the work. Bitbucket: List Workspace Members turns a name into the account the assignee and reviewer fields expect.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can read a pull request with Bitbucket: Get Pull Request Diffstat, pull the change itself with Bitbucket: Compare Commits (Diff), leave a comment on the exact file and line with Bitbucket: Create Pull Request Comment, and record a verdict with Bitbucket: Approve Pull Request or Bitbucket: Request Changes on Pull Request. The read nodes are the safest surface to hand an agent; keep the merge on a human step.

The pull request lifecycle, with the merge kept deliberate

Fourteen nodes cover pull requests end to end: Bitbucket: Create Pull Request and Bitbucket: Update Pull Request for the record, Bitbucket: List Pull Request Activity and Bitbucket: List Pull Request Commits for context, the review verbs including Bitbucket: Unapprove Pull Request, and then the two flagged endings. Bitbucket: Merge Pull Request supports all six Bitbucket merge strategies and changes real code state, and the only undo git offers is a new revert commit, so gate it behind a condition, an approval task, or a manual run. Bitbucket: Decline Pull Request changes no code, but a declined pull request cannot be reopened on Bitbucket Cloud; the only recovery is opening a new one from the same branches.

Deleting things, and the one thing you cannot delete

Bitbucket: Delete Branch is flagged because commits reachable only from that branch become unreferenced and are eventually garbage collected. There is no undelete, so if it was a mistake, recreate the branch from its old head hash immediately with Bitbucket: Create Branch while the hash is still in the run log. Bitbucket: Delete Webhook stops deliveries at once and cannot be restored. Repository deletion is not shipped as a node at all: it is permanent on Bitbucket Cloud, with no trash and no restore, and it destroys the entire git history along with the issues and pull requests attached to it. If you genuinely need to delete a repository, do it by hand in the Bitbucket interface where the confirmation prompt lives.

Reading code without shipping the whole repository

Bitbucket: Get File Content and Bitbucket: Compare Commits (Diff) return raw text as an object of content, truncated, and length, capped at 200,000 characters, which is what makes them safe to feed straight into an AI step instead of pushing bytes through a JSON parser. They are text-only: binary files decode to garbage and files stored in Git LFS return a redirect rather than content, so check size and type first by running Bitbucket: Browse Source with format set to meta. When a summary is enough, Bitbucket: Compare Commits (Diffstat) gives the bounded per-file JSON alternative.

Pipelines spend real money, and webhooks are managed, not received

Bitbucket: Run Pipeline consumes build minutes, a metered paid resource on your Bitbucket plan, so a schedule that triggers builds is spending a real allowance. Poll the run with Bitbucket: Get Pipeline, halt one with Bitbucket: Stop Pipeline, which also stops the billing for it, and read the outcome with Bitbucket: List Deployments and Bitbucket: List Environments. On the webhook side, Bitbucket: List Webhooks and Bitbucket: Create Webhook manage a repository's subscriptions and point Bitbucket events at any URL you operate, with HMAC signing when a secret is set. Secrets are write-only: responses only ever report whether one is set, never the value. There is no inbound Bitbucket trigger node in this integration, so reacting to repository events inside Mattering means polling on a schedule.

Troubleshooting

Test Connection fails with a 401 and the credential is an app password
That is the most likely cause on a first setup, and the error message will not say so. Atlassian removed Bitbucket app passwords permanently on 2026-07-28, so a request carrying one now fails exactly the way a mistyped token does. Create a scoped API token at id.atlassian.com under Security, then API tokens, and update the credential with your Atlassian account email as the username and the new token as the password.
Every node worked for months and now all of them return 401
The API token expired. An expiry date is chosen when the token is created and cannot be extended or refreshed, only replaced, so a healthy connector goes dead on that date with no warning inside Mattering. Create a fresh token with the same scopes, update the credential on the connector, re-run Bitbucket: Get Current User to confirm, and set a calendar reminder before the new expiry.
Test Connection passes but a node returns 403 or a permission error
The token is under-scoped. The connection test only reads the authenticated account, so a token missing repository scopes passes it while the nodes that need those scopes are refused. Scopes are fixed at creation: make a new token with the scopes the workflow needs, for example write:repository:bitbucket for anything that opens, comments on, or merges pull requests, and update the credential. A 403 can also be an account permissions problem rather than a scope problem, so check the account's role in the workspace with Bitbucket: List Workspace Members if a fresh, fully scoped token still fails.
The credential is rejected when the username is a Bitbucket username
Use the Atlassian account email address as the basic auth username. The Bitbucket username works for git over HTTPS but not for REST API calls, and neither does the static x-bitbucket-api-token-auth username that appears in Atlassian's git documentation; that value exists so git clients have something to put in the username slot and has no meaning here. Email plus API token is the only pair this connector accepts.
Every issue node returns 404 on a repository that exists
The repository's issue tracker is switched off, which is the default on new repositories. Turn it on under Repository settings, then Features, or from a workflow with Bitbucket: Update Repository by setting has_issues to true, and the issue nodes start resolving. Until then Bitbucket: List Issues, Bitbucket: Create Issue, Bitbucket: Update Issue, and the issue comment nodes all return 404 rather than an empty list, because the tracker resource genuinely does not exist yet.
Only the first handful of results comes back, or page 2 is empty
Bitbucket paginates collections and returns pagelen, page, size, next, and values. Raise pagelen (up to 100 on most endpoints; the pull request list caps at 50) and page through in the automation. Three lists behave differently: Bitbucket: List Commits, Bitbucket: List Pull Request Activity, and Bitbucket: List Pull Request Commits paginate by opaque hash cursors with no page numbers at all, so setting page on them does nothing. Follow the URL in data.next instead, and never hand-build a page URL for those; Atlassian's own documentation says not to.
A file read comes back as garbage, empty, or cut off
Bitbucket: Get File Content is for text files only. A binary file decodes to garbage, and a file stored in Git LFS returns a redirect rather than the content, so run Bitbucket: Browse Source with format set to meta first to check the size and type before fetching. If the content looks complete but ends abruptly, check the truncated flag on the output: raw text is capped at 200,000 characters on purpose, and the length field tells you what was returned. For a large change, Bitbucket: Compare Commits (Diffstat) is usually the better read than the full diff.
Nodes intermittently return status_code 429
Bitbucket Cloud enforces per-user hourly API limits, and a workflow that sweeps many repositories or pages hard through commits can reach them. The node reports the 429 on its output rather than retrying by itself, so build the backoff into the automation: add a wait step, retry, and spread scheduled sweeps out rather than firing them all on the hour. Reducing the call count helps more than retrying does; a diffstat instead of a full diff, or one wider page instead of five narrow ones, removes requests rather than delaying them.

Bitbucket is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products