| title | description | ms.topic | ms.author | author | ms.date | monikerRange |
|---|---|---|---|---|---|---|
Build Bitbucket Cloud repositories |
Using a Bitbucket Cloud repository with Azure Pipelines |
reference |
vijayma |
vijayma |
10/27/2023 |
azure-devops |
[!INCLUDE version-eq-azure-devops]
Azure Pipelines can automatically build and validate every pull request and commit to your Bitbucket Cloud repository. This article describes how to configure the integration between Bitbucket Cloud and Azure Pipelines.
Bitbucket and Azure Pipelines are two independent services that integrate well together. Your Bitbucket Cloud users do not automatically get access to Azure Pipelines. You must add them explicitly to Azure Pipelines.
You create a new pipeline by first selecting a Bitbucket Cloud repository and then a YAML file in that repository. The repository in which the YAML file is present is called self repository. By default, this is the repository that your pipeline builds.
You can later configure your pipeline to check out a different repository or multiple repositories. To learn how to do this, see multi-repo checkout.
You create a new pipeline by first selecting Bitbucket Cloud for repository type, and then one of the repositories you have access to.
Azure Pipelines must be granted access to your repositories to fetch the code during builds. In addition, the user setting up the pipeline must have admin access to Bitbucket, since that identity is used to register a webhook in Bitbucket.
There are 2 authentication types for granting Azure Pipelines access to your Bitbucket Cloud repositories while creating a pipeline.
| Authentication type | Pipelines run using |
|---|---|
| 1. OAuth | Your personal Bitbucket identity |
| 2. Username and password | Your personal Bitbucket identity |
OAuth is the simplest authentication type to get started with for repositories in your Bitbucket account. Bitbucket status updates will be performed on behalf of your personal Bitbucket identity. For pipelines to keep working, your repository access must remain active.
To use OAuth, login to Bitbucket when prompted during pipeline creation. Then, click Authorize to authorize with OAuth. An OAuth connection will be saved in your Azure DevOps project for later use, as well as used in the pipeline being created.
Note
The maximum number of Bitbucket repositories that the Azure DevOps Services user interface can load is 2,000.
Builds and Bitbucket status updates will be performed on behalf of your personal identity. For builds to keep working, your repository access must remain active.
To create a password connection, visit Service connections in your Azure DevOps project settings. Create a new Bitbucket service connection and provide the user name and password to connect to your Bitbucket Cloud repository.
Continuous integration (CI) triggers cause a pipeline to run whenever you push an update to the specified branches or you push specified tags.
[!INCLUDE ci-triggers]
Note
For Bitbucket Cloud repos, using branches syntax is the only way to specify tag triggers. The tags: syntax is not supported for Bitbucket.
[!INCLUDE ci-triggers]
Note
The Build.SourceVersionMessage variable does not work with Bitbucket repositories when Batch changes while a build is in progress is enabled.
[!INCLUDE ci-triggers]
You can also tell Azure Pipelines to skip running a pipeline that a push would normally trigger. Just include [skip ci] in the message or description of any of the commits that are part of a push, and Azure Pipelines will skip running CI for this push. You can also use any of the following variations.
[skip ci]or[ci skip]skip-checks: trueorskip-checks:true[skip azurepipelines]or[azurepipelines skip][skip azpipelines]or[azpipelines skip][skip azp]or[azp skip]***NO_CI***
[!INCLUDE ci-triggers]
Pull request (PR) triggers cause a pipeline to run whenever a pull request is opened with one of the specified target branches, or when updates are made to such a pull request.
You can specify the target branches when validating your pull requests.
For example, to validate pull requests that
target master and releases/*, you can use the following pr trigger.
pr:
- main
- releases/*This configuration starts a new run the first time a new pull request is created, and after every update made to the pull request.
You can specify the full name of the branch (for example, master) or a wildcard (for example, releases/*).
Note
You cannot use variables in triggers, as variables are evaluated at runtime (after the trigger has fired).
Note
If you use templates to author YAML files, then you can only specify triggers in the main YAML file for the pipeline. You cannot specify triggers in the template files.
Each new run builds the latest commit from the source branch of the pull request. This is different from how Azure Pipelines builds pull requests in other repositories (e.g., Azure Repos or GitHub), where it builds the merge commit. Unfortunately, Bitbucket does not expose information about the merge commit, which contains the merged code between the source and target branches of the pull request.
If no pr triggers appear in your YAML file, pull request validations are automatically enabled for all
branches, as if you wrote the following pr trigger. This configuration triggers a build when any
pull request is created, and when commits come into the source branch of any active pull request.
pr:
branches:
include:
- '*' # must quote since "*" is a YAML reserved character; we want a stringImportant
When you specify a pr trigger, it replaces the default implicit pr trigger, and only pushes to branches that are explicitly configured to be included will trigger a pipeline.
For more complex triggers that need to exclude certain branches, you must use the full syntax as shown in the following example.
# specific branch
pr:
branches:
include:
- main
- releases/*
exclude:
- releases/old*You can specify file paths to include or exclude. For example:
# specific path
pr:
branches:
include:
- main
- releases/*
paths:
include:
- docs
exclude:
- docs/README.mdTips:
- Wild cards are not supported with path filters.
- Paths are always specified relative to the root of the repository.
- If you don't set path filters, then the root folder of the repo is implicitly included by default.
- If you exclude a path, you cannot also include it unless you qualify it to a deeper folder. For example if you exclude /tools then you could include /tools/trigger-runs-on-these
- The order of path filters doesn't matter.
- Paths in Git are case-sensitive. Be sure to use the same case as the real folders.
- You cannot use variables in paths, as variables are evaluated at runtime (after the trigger has fired).
You can specify whether additional updates to a PR should cancel in-progress validation runs for the same PR. The default is true.
# auto cancel false
pr:
autoCancel: false
branches:
include:
- mainYou can opt out of pull request validation entirely by specifying pr: none.
# no PR triggers
pr: noneFor more information, see PR trigger in the YAML schema.
Note
If your pr trigger isn't firing, ensure that you have not overridden YAML PR triggers in the UI.
Select the Pull request validation trigger and check the Enable pull request validation check box to enable builds on pull requests.
You can specify branches to include and exclude. Select a branch name from the drop-down menu and select Include or Exclude as appropriate. For included branches, a build will be triggered on each push to a pull request targeting that branch.
[!INCLUDE informational-runs]
Learn more about informational runs.
[!INCLUDE bb-limitations]
Problems related to Bitbucket integration fall into the following categories:
- Failing triggers: My pipeline is not being triggered when I push an update to the repo.
- Wrong version: My pipeline runs, but it is using an unexpected version of the source/YAML.
[!INCLUDE qa]
- Webhooks are used to communicate updates from Bitbucket to Azure Pipelines. In Bitbucket, navigate to the settings for your repository, then to Webhooks. Verify that the webhooks exist.
[!INCLUDE qa]
[!INCLUDE qa]
[!INCLUDE qa]
[!INCLUDE qa]