Bitbucket Cloud

Spacelift supports Bitbucket Cloud as the code source for your stacks and modules.

You can set up multiple Space-level and one default Bitbucket Cloud integration per account.

Create the Bitbucket Cloud integration

Initial setup

1. On the Source control tab, click Set up integration, then choose Bitbucket Cloud on the dropdown.
2. Integration name: Enter a name for your integration. It cannot be changed later because the Spacelift webhook endpoint is generated based on this name.
3. Integration type: Default (all spaces) or Space-specific. Each Spacelift account can only support one default integration per VCS provider, which is available to all stacks and modules in the same Space as the integration.

Migration from App Passwords to API Tokens

Previously, this integration used Bitbucket App Passwords for authentication. Atlassian has deprecated App Passwords and replaced them with API tokens.

Create your API token

You will need to create an API token for this integration on the Bitbucket Cloud site.

1. Navigate to Atlassian account settings > Security > Create API token with scopes.

2. Fill in the details to create a new API token:

   1. Choose a name for your API token.
   2. Set an expiration date.

   3. Select Bitbucket as the app.

      

   4. Select read permissions for:

      • Repository
      • Pull requests

      

3. Click Create.

4. Copy the API token details to finish the integration in Spacelift.

Copy details into Spacelift

Now that your API token has been created, return to the integration configuration screen in Spacelift.

1. Email: Enter your Bitbucket Cloud email address.
2. API token: Paste the API token that Spacelift will use to access your Bitbucket Cloud repository.
3. Labels: Organize integrations by assigning labels to them.
4. Description: A markdown-formatted free-form text field to describe the integration.
5. Click Set up to save your integration details.

Set up webhooks

For every Bitbucket Cloud repository being used in Spacelift stacks or modules, you will need to set up a webhook to notify Spacelift about project changes.

Note

Default integrations are visible to all users of the account, but only root Space admins can see their details.

Space-level integrations will be listed to users with read access to the integration Space. Integration details, however, contain sensitive information (such as the webhook secret) and are only visible to those with admin access.

1. On the Source code page, click the three dots next to the integration name.
2. Click See details to find the webhook endpoint and webhook secret.

Configure webhooks in Bitbucket Cloud

For each repository you want to use with Spacelift, you now need to add webhooks in Bitbucket Cloud.

1. In Bitbucket Cloud, select the repository you are connecting to Spacelift.
2. Navigate to Repository settings > Webhooks.
3. Click Add webhook.
4. Title: Enter a name for the webhook.
5. URL: Paste the webhook endpoint from Spacelift.
6. Secret: Paste the webhook secret from Spacelift.
7. Status: Check Active.
8. Triggers:
   1. Under Repository, check Push.
   2. Under Pull Request, check:
      • Created
      • Updated
      • Approved
      • Approval removed
      • Merged
      • Comment created
9. Click Save.

Install Pull Request Commit Links app

Finally, you should install the Pull Request Commit Links app to be able to use this API. The app is installed automatically when you go to the commit's details and click Pull requests.

Use the Bitbucket Cloud integration

When creating a stack, you will now be able to choose the Bitbucket Cloud provider and a repository inside of it:

Troubleshooting

If you're receiving a 401 error, use this command to check the username and password:

curl -v -u your_username:some_app_password "https://api.bitbucket.org/2.0/workspaces/workspace_id"

And this to check if some repositories may not be showing up:

curl -s -u your_username:some_app_password "https://api.bitbucket.org/2.0/repositories" | jq

Use Spacelift checks to protect branches

You can use commit statuses to protect your branches tracked by Spacelift stacks by ensuring that proposed runs succeed before merging their Pull Requests.

Aggregated checks

Info

This feature is only available to Business plan and above. Please check out our pricing page for more information.

If you have multiple stacks tracking the same repository, you can enable the Aggregate VCS checks feature in the integration's settings. This will group all the checks from the same commit into a predefined set of checks, making it easier to see the overall status of the commit.

When the aggregated option is enabled, Spacelift will post the following checks:

• spacelift/tracked: Groups all checks from tracked runs
• spacelift/proposed: Groups all checks from proposed runs
• spacelift/modules: Groups all checks from module runs

The summary will look like this:

Delete the Integration

If you no longer need the integration, you can delete it by clicking the 3 dots next to the integration name on the Source code tab, and then clicking Delete. You need admin access to the integration Space to be able to delete it.

Warning

You can delete source code integrations while stacks are still using them, which will have consequences.

Consequences

When a stack has a detached integration, it will no longer be able to receive webhooks from Bitbucket and you won't be able to trigger runs manually either.

To fix the issue, click the stack name on the Stacks tab, navigate to the Settings tab, and choose a new integration.

Tip

You can save a little time if you create the new integration with the exact same name as the old one. This way, the webhook URL will remain the same and you won't have to update it in Bitbucket.