Setup takes about 5 minutes.

Introduction

Use the Bitbucket connector when you want Foundational to access source code in Bitbucket. The setup uses an API access token and supports standard Bitbucket Cloud deployments.

To make the connection, you need to:

Create or assign an API access token
Grant the required access permissions
Create user credentials
Connect Foundational to Bitbucket

Prerequisites

Ensure you have:

Access to Bitbucket
Permissions to create an API access token
Group or project Maintainer access to create the required webhooks
Open pull requests on your behalf

Access permissions

Access to Bitbucket allows Foundational to determine data lineage and analyze pending and historical pull requests. Permissions are granted through a Bitbucket API access token.

Foundational requires access so it can:

Read repository source code
Read pull requests
Receive webhook events
Comment on pull requests

Create or assign user credentials

Bitbucket authentication uses an API access token.

Select one option.

Option 1: Workspace access token (preferred)

Use a workspace access token to cover all repositories in a workspace.

In Bitbucket, create a workspace access token. See the Bitbucket article Create an access token for a workspace.
Assign the following permissions. Each permission has separate checkboxes for Read and Write in the Bitbucket UI. Select each checkbox individually to assign the permissions:
- Repositories: Read
- Repositories: Write
- Webhooks: Read
- Webhooks: Write
- Pipelines: Read
- Pipelines: Write
- Pull Requests: Read
- Pull Requests: Write
NOTE: Foundational uses pull request permissions to open PRs on your behalf using Foundational IQ. To automate pull requests, Foundational needs write permissions on your repositories and pull requests.
Give the token a descriptive name (e.g., foundational-app). This name appears as the author of Foundational pull request comments.
Set the longest expiry allowed by your policy to reduce service disruptions.

Option 2: Repository access token

Use this option if you cannot use a workspace access token. See the Bitbucket article Access tokens for a repository.

Create a repository access token for each repository you want to cover.
Assign the following permissions. Each permission has separate checkboxes for Read and Write in the Bitbucket UI. Select each checkbox individually to assign the permissions:
- Repositories: Read
- Repositories: Write
- Webhooks: Read
- Webhooks: Write
- Pipelines: Read
- Pipelines: Write
- Pull Requests: Read
- Pull Requests: Write
NOTE: Foundational uses pull request permissions to open PRs on your behalf using Foundational IQ. To automate pull requests, Foundational needs write permissions on your repositories and pull requests.

Connect Foundational to Bitbucket

Bitbucket access tokens are immutable. Once created, you cannot add or modify permissions. If you have an existing connection:

Create a new token using Option 1 or Option 2 in Create or assign user credentials.
Follow the connection steps to update your credentials in Foundational.

In Foundational, open the Connectors & Integrations page.
In Source Control, select the Bitbucket card and click Connect.
Click Add Access Key.
The initial setup screen opens. Click Start Setup.
The Set Up New Connection screen opens.

Enter the details:
- API Access Token: The workspace or repository access token you created earlier.
- Workspace ID: The first part of the Bitbucket URL after bitbucket.org. Example:. For https://bitbucket.org/foundational-io, the Workspace ID is foundational-io.
Click Next.
The final setup screen opens. To complete the connection, click Save.