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.
Connect Bitbucket to Mattering
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
Every node worked for months and now all of them return 401
Test Connection passes but a node returns 403 or a permission error
The credential is rejected when the username is a Bitbucket username
Every issue node returns 404 on a repository that exists
Only the first handful of results comes back, or page 2 is empty
A file read comes back as garbage, empty, or cut off
Nodes intermittently return status_code 429
Related
The Bitbucket MCP
What connecting Bitbucket unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.