Skip to main content
You can set up an integration with either Bitbucket Cloud or a self-hosted Bitbucket Server.

​
Bitbucket Cloud

​
1. Create an OAuth consumer

To integrate your Upsun project with an existing Bitbucket Cloud repository, create an OAuth consumer: A screenshot of how to setup the Bitbucket OAuth consumer
Be sure to define the above as a private consumer by checking the This is a private consumer box.
The Callback URL isn’t important in this case. You can set it to http://localhost. Copy the Key and Secret for your consumer.

​
2. Enable the Cloud integration

To enable the integration, use either the CLI or the Console.
Run the following command:
upsun integration:add \
  --project <VariableBlock name="PROJECT_ID" /> \
  --type bitbucket \
  --repository <VariableBlock name="OWNER/REPOSITORY" /> \
  --key <VariableBlock name="CONSUMER_KEY" /> \
  --secret <VariableBlock name="CONSUMER_SECRET" />
For example, if your repository is located at https://bitbucket.org/platformsh/platformsh-docs, the command is similar to the following:
upsun integration:add \
  --project abcdefgh1234567 \
  --type bitbucket \
  --repository platformsh/platformsh-docs \
  --key abc123 \
  --secret abcd1234 \
In both the CLI and Console, you can choose from the following options:
CLI flagDefaultDescription
fetch-branchestrueWhether to mirror and update branches on Upsun and create inactive environments from them. When enabled, merging on an Upsun environment isn’t possible. That is, merging environments must be done on the source repository rather than on the Upsun project. See note below for details related to this flag and synchronizing code from a parent environment.
prune-branchestrueWhether to delete branches from Upsun that don’t exist in the Bitbucket repository. When enabled, branching (creating environments) must be done on the source repository rather than on the Upsun project. Branches created on Upsun that are not on the source repository will not persist and will be quickly pruned. Automatically disabled when fetching branches is disabled.
build-pull-requeststrueWhether to track all pull requests and create active environments from them, which builds the pull request.
resync-pull-requestsfalseWhether to sync data from the parent environment on every push to a pull request.
resources-initfalseTo specify a resource initialization strategy for new containers. Once set, the strategy applies to all the deployments you launch through your source integration. See more information on available resource initialization strategies.
To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches and prune-branches options.

​
Bitbucket Server

​
1. Generate a token

To integrate your Upsun project with a repository on a Bitbucket Server instance, you first need to create an access token associated with your account. Generate a token. and give it at least read access to projects and admin access to repositories. Copy the token.

​
2. Enable the Server integration

​
Source of truth

​
Sync, fetch, and prune

Last modified on March 11, 2026