Skip to main content

Bitbucket

Overview​

Integrating StackGuardian with Bitbucket allows you to leverage Infrastructure and Policy as Code from your Bitbucket repositories. To set up the integration, you will need to authenticate StackGuardian Bitbucket connector using one of the following methods:

  • API Token
  • Access Token
  • App Password (Legacy support – soon to be deprecated by Bitbucket)

This document explains all three authentication methods and how to configure the Bitbucket connector in StackGuardian.

Key Features​

Create API Token​

To integrate Bitbucket, you first need to create an API Token in Bitbucket with limited permissions. Follow these steps to create an API Token in Bitbucket:

  1. Login to Bitbucket
  2. Navigate to Settings (upper-right corner of the top navigation bar).
  3. Under Personal Settings, go to Atlassian account settings.
  4. Select Security from the top navigation bar.
  5. Under API tokens, click on Create and manage API tokens.
  6. Click on Create API token with scopes.
  7. Provide a Name for the API token.
  8. Set an Expires on date (this is the date when the API Token will expire. Choose a long validity period so that StackGuardian integration continues to work).
  9. Click on Next.
  10. On the Select the app page, under Select API token app, select Bitbucket.
  11. Click on Next.
  12. Under Select bitbucket scopes, Select all of the following scopes (these scopes are required to get read access to the Bitbucket repositories):
    • Account: Read
    • Me: Read
    • Project:bitbucket: Read
    • Pullrequest:bitbucket: Read
    • Repository:bitbucket: Read
    • User:bitbucket: Read
    • Workspace:bitbucket: Read

create_api_token

  1. Click on Next.
  2. Review the details of your API Token and click Create token if it all looks good.

review_api_token

  1. Copy the generated API Token and securely store it. The API Token is displayed only once and cannot be retrieved later.

api-token

Create Access Token​

To integrate Bitbucket, you first need to create an Access Token in Bitbucket with limited permissions (it’s possible to create an Access Token for a project, a repository or a workspace).

1. Access Token for Repository​

Follow these steps to create an Access Token for a repository in Bitbucket:

  1. Login to Bitbucket.
  2. Navigate to target repository for the Access Token (this repository is the only one that the Access Token can access).
  3. On the sidebar, select Repository Settings.
  4. Under Security, select Access Tokens.
  5. Click on Create Access Token.
  6. Provide a Name for the Access Token.
  7. Under Expiry, set an Expires on date (select the date which your Access Token will expire. Choose a long validity period, so that StackGuardian integration continues to work).
  8. Select the permissions the Access Token needs (for detailed descriptions of each permission, see Repository-level access token permissions):
    • Repositories: Read

repo-create-access-token

  1. Click on Create to generate the new Access Token.
  2. Copy the generated Access Token and securely store it. The Access Token is displayed only once and cannot be retrieved later.

repo-create-access-token

2. Access Token for Project​

Follow these steps to create an Access Token for a project in Bitbucket:

  1. Login to Bitbucket.
  2. Navigate to target project for the Access Token (this project is the only one that the access token can access).
  3. On the sidebar, select Project Settings.
  4. Under Security, select Access Tokens.
  5. Click on Create Access Token.
  6. Provide a Name for the Access Token.
  7. Under Expiry, set an Expires on date (select the date which your Access Token will expire. Choose a long validity period, so that StackGuardian integration continues to work).
  8. Select the permissions the Access Token needs. (for detailed descriptions of each permission, see Repository-level access token permissions):
    • Projects: Read
    • Repositories: Read

project-create-access-token

  1. Click on Create to generate the new Access Token.
  2. Copy the generated Access Token and securely store it. The Access Token is displayed only once and cannot be retrieved later.

project-copy-access-token

3. Access Token for Workspace​

Follow these steps to create an Access Token for a workspace in Bitbucket:

  1. Login to Bitbucket.
  2. Navigate to target workspace for the Access Token (this workspace is the only one that the Workspace Access Token can access).
  3. On top bar navigation, Select Settings.
  4. On dropdown menu, select Workspace Settings.
  5. Under Security, select Access Tokens.
  6. Click on Create Access Token.
  7. Provide a Name for the Access Token.
  8. Under Expiry, set an Expires on date (select the date which your Access Token will expire. Choose a long validity period, so that StackGuardian integration continues to work).
  9. Select the permissions the Access Token needs (for detailed descriptions of each permission, see Repository-level access token permissions):
    • Account: Read
    • Projects: Read
    • Repositories: Read

workspace-create-access-token

  1. Click on Create to generate the new Access Token.
  2. Copy the generated Access Token and securely store it. The Access Token is displayed only once and cannot be retrieved later.

workspace-create-access-token

Create App Password (will soon be deprecated)​

warning

Bitbucket will deprecate App Passwords on 9th June 2026. Instead, use API or Access Tokens. For the App Password deprecation timeline and more information, visit the Bitbucket blog.

To integrate Bitbucket, you first need to create an App Password in Bitbucket with limited permissions. Follow these steps to create an App Password in Bitbucket:

  1. Log in to Bitbucket.
  2. Navigate to Settings (upper-right corner of the top navigation bar).
  3. Under Personal Settings, select Personal Bitbucket settings.
  4. On the left sidebar, click on App Passwords.
  5. Click on Create App Password.
  6. Provide a Label for the app password.
  7. Under Permissions, select the following:
    • Account: Read
    • Projects: Read

app-password

  1. Click on Create to generate the new App Password.
  2. Copy the generated App Password and securely store it. The App Password is displayed only once and cannot be retrieved later.

app-password

Create a Bitbucket VCS Connector on the StackGuardian Platform​

To create a Connector, open the StackGuardian Platform and follow these steps:

  1. Go to the "Connectors > Version Control Providers" tab in the StackGuardian Orchestrator.
  2. Select "Connect to Bitbucket."
  3. Enter a Connector name, Description, Tag.
  4. Select one Bitbucket authentication type.
  5. Provide the required authentication information based on your chosen method:
  • API Token: Enter Bitbucket User Name, Bitbucket Email, and paste the API Token that was created earlier in Bitbucket.

Create API Token

  • Access Token: paste the Access Token that was created earlier in Bitbucket (only Access Token is required).

Create Access Token.jpg

  • App Password: Enter Bitbucket User Name, and paste the App Password that was created earlier in Bitbucket.

Create App password.jpg

  1. Click on Create.

Create Connector Flow

Update a Bitbucket VCS Connector on StackGuardian Platform​

To update a Connector, open the StackGuardian Platform and follow these steps:

  1. Go to the "Connectors > Version Control Providers" tab in the StackGuardian Orchestrator.
  2. Select the Connector you want to update.
  3. Switch the authentication type to the one you want (Updating or switching the authentication type clears previously saved credentials; you must re-enter all required fields for the selected type to proceed).
  4. Enter Bitbucket Username, Bitbucket Email (only for API Token), and paste the new API Token or Access token that was created earlier in Bitbucket.
  5. Click on Save.

Update Connector Flow

Migration Guide for App Password​

Bitbucket will deprecate App Passwords on 9th June, 2026. To ensure uninterrupted access to your Bitbucket repositories via StackGuardian, we recommend you to migrate any existing Bitbucket VCS connectors that use App Passwords to either API Tokens (recommended) or Access Tokens, as soon as possible. After the deprecation, connectors using App Passwords will no longer work and all Workflows and Templates relying on them will stop working. For more information, see Bitbucket's official announcement.

1. Step-by-step guide to help you do this Migration:​

  • Identify Connectors Using App Passwords

    • Navigate to Connectors → Version Control Providers in StackGuardian.
    • Review which connectors use App Password authentication.

  • Generate a Bitbucket API Token (Recommended) or Access Token

    • Log in to Bitbucket.
    • Create a new API Token or Access token with the required scopes for StackGuardian.
    • Copy the token securely.

  • Update StackGuardian Connector

    When updating a Bitbucket authentication type (App Password, API token or Access Token) it is also required to update your User Name and Email.

    • Select the existing connector using App Password.
    • Switch authentication type from App Password to API Token or Access token.
    • Enter Bitbucket Username, Bitbucket Email (only for API Token), and paste the new API Token or Access token that was created earlier in Bitbucket.
    • Click on Save.

Update Connector Flow

2. Deprecation Timeline​

Bitbucket’s App Password deprecation will occur in three stages:

  • ✅ Current – Until September 9, 2025

    • Users can generate new App Passwords in Bitbucket.
    • Existing Bitbucket VCS connectors in StackGuardian using App Passwords will continue to work.
    • New Bitbucket connectors in StackGuardian can be created using new or existing App Passwords, API Tokens or Access Tokens.

  • ⚠️ Limited Availability – September 9, 2025 to June 9, 2026

    • New App Passwords cannot be generated in Bitbucket; users are encouraged to create API Tokens.
    • New Bitbucket connectors in StackGuardian with App Passwords can only be created if you already have valid/existing App Passwords. You can also create new Bitbucket connectors with API Tokens or Access Tokens.
    • Existing connectors using App Passwords will continue to work.
    • StackGuardian will support App Passwords until June 9, 2026.

  • ❌ Removal – After June 9, 2026

    • Bitbucket will completely disable App Passwords.
    • All connectors in StackGuardian using App Passwords will stop working, as well as any workflows and templates relying on them.
    • All new connectors must use API Tokens or Access Tokens.