Bitbucket integration¶

Pulse integrates with Bitbucket Cloud to receive data about changes, deployments, and incidents, necessary to calculate the Accelerate metrics:

Deployment frequency
Lead time for changes, including the following drill-down metrics:
Time to recover
Change failure rate

Setting up the Bitbucket integration¶

Note

The Bitbucket integration connects to a specific workspace. You must be the owner of that Bitbucket workspace to proceed with the integration setup.
See below the permissions that Pulse requires from your Bitbucket account.

To set up the Bitbucket integration:

On Pulse, expand Integrations and select Bitbucket.
Click Install Bitbucket App.
Confirm that Pulse successfully connected the integration to Bitbucket. If there is an error please contact support.
Choose the workspace that you want to connect the integration to. You can only select a workspace where you have owner permissions.
Choose the strategy to detect incidents that best fits your workflows. See the section below for a detailed description of each option.
Click Complete setup.

Your Bitbucket integration is now complete. Pulse will start loading your data for the last 90 days.

Pulse Bitbucket integration set up successfully

Automatic deployment detection using merged pull requests¶

Note

Pulse uses your merged pull requests to automatically detect your deployments. Other strategies to detect deployments will be available with a future version of Pulse.
If you use a squash merge strategy when merging the pull request, Pulse may produce inaccurate accelerate metrics.

Pulse considers a deployment every merged pull request that targets the default branch of the repository.
The deployment date is the timestamp when the corresponding pull request is merged.
The set of changes in a deployment is the list of commits in the corresponding pull request.
Pulse associates all the Bitbucket user groups of the author of a merged pull request with the corresponding deployment, excluding the user groups with less than two members. Pulse only takes the changes to Bitbucket user groups into account on pull requests merged after those changes.

Automatic incident detection strategies¶

The Pulse Bitbucket integration can detect incidents automatically using the following strategies:

Pull request reverts
Pull request naming convention

You can also choose not to detect incidents via Bitbucket.

Use pull request reverts (based on default branch)¶

Pulse bases incident detection on pull request reverts.
Pulse considers an incident any pull request that targets the default branch of the repository merged from a branch whose name starts with revert-pr-, getting the number of the reverted pull request from the branch name, revert-pr-<pull request number>. If you change the name of the branch created by Bitbucket when you revert a pull request, Pulse may not be able to obtain the incident data correctly.
The incident creation date is the timestamp when the reverted pull request was initially merged. If Pulse can't get the reverted pull request number from the branch name, the incident creation date is the timestamp of the first commit to the incident pull request.
Pulse associates incidents to the system matching the repository name.

Use pull request naming convention (based on default branch)¶

Pulse applies the same mechanism to detect incidents used for the pull request reverts strategy. However, instead of considering branches whose name starts with revert-pr-, Pulse uses the prefix that you define for the branch name or the pull request title to match the naming convention of your workflow.
Your prefix must have 2 to 50 characters. For a branch name, your prefix can't contain spaces or special characters, such as ~ ^ : ? * [. See the Git reference for further details.

Don't detect incidents via Bitbucket¶

Pulse doesn't detect incidents automatically using Bitbucket events.

Choose this option if you want to send to Pulse the information about your incidents using another Pulse integration - Jira one-click integration, PagerDuty one-click integration, Pulse CLI, or Ingestion API - or if you don't want Pulse to track incidents data.

Collected data¶

The table below lists the data that the Bitbucket integration collects from your Bitbucket workspace, together with:

The mapping between the data collected from Bitbucket and the Pulse data model
The metrics that Pulse displays on the dashboards, calculated using the collected data

Data collected from Bitbucket	Mapping to Pulse data model	Used in
Pull request commits	Changes: `change_id`: commit UUID `time_created`: commit author date¹ `system`: repository name	Lead time for changes on the Accelerate Overview dashboard
Pull requests	Deployments: `deploy_id`: unique pull request identifier `timestamp_created`: merge date of the pull request `system`: repository name	Deployment frequency and Change failure rate on the Accelerate Overview dashboard
Pull requests	Incidents: `incident_id`: pull request number `timestamp_created`: merge date of the reverted pull request `timestamp_resolved`: merge date of the pull request `system`: repository name	Time to recover and Change failure rate on the Accelerate Overview dashboard
Pull requests	-	Changes & Reviews dashboard, Work in Progress dashboard
User groups	Deployments: `teams`: Bitbucket user groups of the author of a deployment²	Filters the Accelerate Overview dashboard, Changes & Reviews dashboard, and Work in Progress dashboard by the contributions made by the team

¹: Pulse uses the commit author's date since it's more accurate. The committer date can be changed (for example, with a fast-forward) and stop reflecting the real creation date of the change.

²: Adding a new user group or changing the composition of a user group on Bitbucket only affects new data starting from that moment and doesn't have an immediate impact on the dashboards. Also, deleted user groups on Bitbucket are still visible in Pulse.

Which permissions does Pulse need from Bitbucket?¶

Pulse requests only the necessary permissions/scopes from Bitbucket to collect changes and deployment data from the repositories in your workspace and keeps your information secure. See below the detailed list of permissions.

Scope and permissions	Description
`account`	Pulse retrieves the email of the user installing the integration, the user's workspaces and its membership, and the user groups.
`repository`	Pulse retrieves repository information to get the default branch and the list of commits.
`pullrequest`	Pulse retrieves pull request information to calculate several metrics presented on the dashboards. See the details here.
`webhook`	Pulse creates webhooks to track new or deleted workspaces. Pulse creates webhooks subscribed to the following events as a trigger to gather the corresponding data in real time: `pullrequest:created`: pull requests creation `pullrequest:updated`: pull requests edition `pullrequest:fulfilled`: pull requests merge `pullrequest:rejected`: pull requests decline `pullrequest:approved`: pull requests approval `pullrequest:unapproved`: deletion of pull requests approval `pullrequest:changes_request_created`: pull requests change request `pullrequest:changes_request_removed`: deletion of pull requests change request `repo:push`: pushes of tags to a repository Pulse creates webhooks subscribed to the following events as a trigger to historical data import: `repo:transfer`: repositories tranfer acceptance `repo:fork`: repositories fork