Bitbucket Cloud

In brief: Bitbucket Cloud integration maps tests and plans folders, syncs through pull requests, and applies inbound push and merged pull request webhooks.

Bitbucket integration is project-level and Bitbucket Cloud only. You connect TestChimp to one repository with a repository or workspace access token. You create the webhook in Bitbucket. A project uses one git provider at a time.

Bitbucket Data Center uses a different API and is not supported.

ChimpHands sessions are available for GitHub-connected projects. For a Bitbucket project, the sidebar item stays visible and explains that limit on hover.

Prerequisites

• A Bitbucket Cloud repository where you can create an access token and a webhook.
• TestChimp project with Bitbucket integration enabled.
• Network path from Bitbucket Cloud to your TestChimp ingress host (webhook delivery).

Overview of setup

1. Create a Bitbucket Cloud repository or workspace access token.
2. Paste the token in TestChimp and Connect.
3. Create a repository webhook for Repository push and Pull request merged, using the webhook URL and secret from TestChimp.
4. Select the repository and map Tests and Plans folders.

Step 1: Create an access token

In Bitbucket Cloud, open Repository settings → Access tokens (or workspace access tokens) and create a token with:

Scope	Why
Repository read and write	List the repo, read files, and commit sync changes
Pull request read and write	Open pull requests for SmartTests and plan sync

Paste the token into TestChimp once. App passwords are not supported. Send the token as a bearer credential; TestChimp does that for you.

Step 2: Configure TestChimp

In TestChimp → Project settings → Integrations → Bitbucket:

1. Access token — paste the token from Step 1.
2. Webhook URL — copy the URL shown in TestChimp ({ingress-host}/bitbucket-webhook/{projectId}).
3. Webhook secret — choose a secret, paste it here, and use the same value on the Bitbucket webhook.

Click Connect to validate the token. Use Save settings after you set or change the webhook secret.

Step 3: Create the repository webhook

In Bitbucket → your repository → Repository settings → Webhooks:

1. URL — paste the Webhook URL from TestChimp.
2. Secret — paste the same secret you saved in TestChimp. TestChimp checks X-Hub-Signature (sha256= HMAC-SHA256 of the raw body).
3. Triggers — enable the events TestChimp handles:

Trigger	Required	Purpose
Repository push	Yes	Import commits that touch mapped tests or plans paths, including branch create and delete
Pull request → Merged (pullrequest:fulfilled)	Yes	After a pull request merges, reconcile sync state for the files in that pull request

Other events are ignored.

Step 4: Select repository and map folders

After Connect succeeds:

1. Select the repository (workspace/repo-slug).
2. Map Tests folder — SmartTests root.
3. Map Plans folder — markdown test-planning root.

Initial mapping may open pull requests on your default branch with prefixes testchimp-test-initial-map-… and testchimp-plan-initial-map-…. If the repository enforces branch naming rules, allow branches starting with testchimp-.

Step 5: Sync SmartTests and export plans

• SmartTests — use the branch selector and Sync with Bitbucket in the SmartTests IDE.
• Test planning — Import/Export → Sync to Git Repo opens a pull request for plan changes. See Export to Git.

Inbound sync (Git → TestChimp)

Webhook	When	Behavior
Repository push	Commits pushed to a branch	Applies added, modified, and removed paths under mapped tests and plans folders
Repository push (branch delete)	The new branch ref is null	Archives branch metadata in TestChimp
Pull request merged	A pull request is fulfilled	Reconciles sync metadata for changed paths on the destination branch

CI test reporting

Bitbucket Pipelines already sets CI=true, which TestChimp treats as a CI run. Set TESTCHIMP_API_KEY to the project API key. If the checkout is detached, also set TESTCHIMP_BRANCH_NAME and TESTCHIMP_GIT_COMMIT_SHA.

See also

• Code repository overview
• GitHub Sync (SmartTests workflow)
• Export plans to Git