Bitbucket integration

What it does

The Bitbucket integration lets you run developer-workflow automations on behalf of any client whose Bitbucket Cloud workspace you manage. Connect a workspace once, then list repositories and pull requests, open issues, raise and decline pull requests, and route live repository events (push, pull request created, pull request updated) into the rest of your workflow without writing any code.

Connect a Bitbucket account

1. In TaskJuice, open Settings -> Connections and choose Add connection -> Bitbucket.
2. Enter your client's Bitbucket workspace slug (the part after bitbucket.org/ in workspace URLs, e.g. acme for bitbucket.org/acme).
3. Enter the Bitbucket username for the account TaskJuice should act as. The username lives under Personal settings -> Account settings -> Username in Bitbucket and is not the same as the sign-in email.
4. In Bitbucket, open Personal settings -> App passwords, choose Create app password, grant the Repositories (read, write), Pull requests (read, write), and Issues (read, write) scopes, and paste the generated token into the Bitbucket App Password field.

The connection is read- and write-capable across repositories, issues, and pull requests scoped to that account. Rotate or revoke the app password from the same Personal settings -> App passwords page at any time.

Triggers

• bitbucket/repo-push. Fires when commits are pushed to a branch or tag of a Bitbucket repository.
• bitbucket/pull-request-created. Fires when a new pull request is opened on a Bitbucket repository.
• bitbucket/pull-request-updated. Fires when an existing pull request is updated (title, description, branches, reviewers, or commits).

Every trigger verifies the inbound POST against a shared-secret header. In Bitbucket, open Repository settings -> Webhooks, choose Add webhook, point it at the TaskJuice incoming webhook URL, paste the shared secret into the Secret field, and tick the matching event (Repository push, Pull request created, or Pull request updated). Bitbucket forwards the secret in the X-Hub-Signature request header so TaskJuice can verify the source.

Actions

• bitbucket/list-repositories. List repositories in the connected workspace, with optional Bitbucket Query Language filtering, sort field, and role filter.
• bitbucket/get-repository. Retrieve a single repository by slug.
• bitbucket/create-issue. Open a new issue on a repository with a title, Markdown description, kind, priority, and assignee.
• bitbucket/list-pull-requests. List pull requests on a repository, filtered by state (OPEN, MERGED, DECLINED, SUPERSEDED) or a Bitbucket Query Language expression.
• bitbucket/create-pull-request. Open a new pull request between two branches with a title, description, and optional reviewers.
• bitbucket/decline-pull-request. Decline an open pull request without merging it.

Known limitations

• Rate limits follow Bitbucket Cloud's documented hourly quotas per app password (see Bitbucket Cloud API rate limits). TaskJuice retries on 429 responses honoring the Retry-After header.
• Page-based pagination is fixed at 10 items per page on most endpoints. TaskJuice stops paginating after 100 pages by default; raise the ceiling on the action if you need a deeper sweep.
• App password authentication is scoped to the user that created the password. Switching accounts requires generating a new app password under that user and rotating the connection.
• The issue tracker must be enabled on the repository for bitbucket/create-issue to succeed; Bitbucket disables it by default on new repositories.
• Bitbucket webhooks are unsigned by default. TaskJuice relies on the optional shared secret being configured in the webhook to authenticate inbound POSTs; webhooks without a secret are rejected.