Bitbucket Cloud
Port's Bitbucket integration allows you to model Bitbucket cloud resources in your software catalog and ingest data into them.
Core support
This documentation covers Port's integration with Bitbucket Cloud. For information about integrating with Bitbucket Server (Self-Hosted), please refer to the Bitbucket Server integration documentation.
Prerequisites
- A Bitbucket Cloud account with admin privileges to the workspace you want to ingest data from.
- If you choose the real time & always on installation method, you will need a kubernetes cluster on which to install the integration.
- Your Port user role is set to
Admin.
Setup
Create authentication credentials
Bitbucket is deprecating app passwords. As of September 9, 2025, new app passwords cannot be created, and existing ones will be disabled on June 9, 2026. Use user-scoped tokens or workspace tokens instead.
The integration supports three authentication methods:
-
Workspace Token (Recommended for Premium accounts)
- Most scalable option for large organizations
- Supports multiple tokens (comma-separated) to distribute load and avoid rate limits
- Create a workspace token
- Note: Workspace tokens are a Bitbucket Premium feature
- Required scopes:
workspace:readproject:readrepository:readpullrequest:readwebhooks:readandwrite
-
User-Scoped Token (Replacement for App Passwords)
- Required for new setups using the
filekind (existing app passwords also work, but can't be created anymore) - Works in free Bitbucket environments
- Requires user's email address for authentication
- Create a user-scoped token
- Required scopes:
- Read:
read:repository:bitbucket,read:project:bitbucket,read:pullrequest:bitbucket,read:webhook:bitbucket,read:workspace:bitbucket - Write:
write:webhook:bitbucket
- Read:
- Required for new setups using the
-
App Password (Deprecated)
- ⚠️ Being phased out by Bitbucket - migrate to user-scoped tokens
- Requires username and app password combination
- Create an app password
- Required scopes:
workspace:readproject:readrepository:readpullrequest:readwebhooks:readandwrite
We recommend using multiple workspace tokens for the integration, as this provides better security and scalability. Using multiple tokens helps distribute the load and avoid rate limiting issues.
If using user-scoped tokens or app passwords, consider using a dedicated account, as credentials from the same Bitbucket account share rate limits.
Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.
The prerequisites required for installation are listed below.
-
Go to the BitbucketCloud Connectors page in Port.
-
Under
Select your installation method, chooseHosted by Port. -
Configure the
Installation parametersandAdvanced configurationas you wish (see below for details).
Installation parameters
Each integration requires specific parameters (such as an API token, a URL, etc.), as seen in Port's UI when installing it. Hover over the ⓘ icon next to each parameter to see more details about it.
Advanced configuration
- During the installation process each integration may have additional settings under the
Advanced configurationsection in Port's UI. Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Connectors page and navigate to theSettingtab. Hover over the ⓘ icon next to each setting to see more details about it.
Port secrets
Some integration settings require sensitive pieces of data, such as tokens. For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.
When filling in such a setting, its value will be obscured (shown as ••••••••).
For each such setting, Port will automatically create a secret in your organization.
To see all secrets in your organization, follow these steps.
Port source IP addresses
When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:
- Europe (EU):
54.73.167.226,63.33.143.237,54.76.185.219 - United States (US):
3.234.37.33,54.225.172.136,3.225.234.99
-
Go to the Bitbucket-Cloud Connectors page in your portal.
-
Select the
Self-hostedmethod. -
A
helmcommand will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.
Scalable mode for large integrations
If you are deploying the integration at scale and want to decouple the resync process from the live events process (recommended for large or high-throughput environments), you can enable scalable mode by adding the following flags to your Helm install command:
--set workload.kind="CronJob" \
--set workload.cron.resyncTimeoutMinutes=60 \
--set scheduledResyncInterval="'*/60 * * * *'" \
--set liveEvents.worker.enabled=true
Required parameters:
port.clientId- Your port client id.port.clientSecret- Your port client secret.port.baseUrl- Your Port API URL -https://api.port.iofor EU,https://api.us.port.iofor US.integration.identifier- Change the identifier to describe your integration.integration.type- The integration type.integration.eventListener.type- The event listener type.integration.config.bitbucketWorkspace- The workspace of the Bitbucket Cloud account.
Optional parameters (click to expand)
integration.config.bitbucketUserEmail- The email address for user-scoped token authentication (required when using user-scoped token).integration.config.bitbucketUsername- The username for app password authentication (required when using app password - deprecated).integration.config.bitbucketUserScopedToken- The user-scoped token for the Bitbucket Cloud account (replaces app password, required for file kind).integration.config.bitbucketAppPassword- (Deprecated) The app password of the Bitbucket Cloud account - usebitbucketUserScopedTokeninstead.integration.config.bitbucketWorkspaceToken- The workspace token(s) for the Bitbucket Cloud account (can be a single token or comma-separated string of multiple tokens).integration.config.webhookSecret- The secret used to verify the webhook requests.scheduledResyncInterval- The number of minutes between each resync.initializePortResources- Default true, When set to true the integration will create default blueprints and the port App config Mapping.sendRawDataExamples- Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true.liveEvents.baseUrl- The base url of the instance where the Bitbucket Cloud integration is hosted, used for real-time updates. (e.g.https://mybitbucketcloudoceanintegration.com).
If you're running high volumes of live events in a self-hosted deployment and want better reliability, event durability, or horizontal scalability, you can optionally set up Port's dedicated live events infrastructure. See live events at scale for details.
Recommended resource sizes
To ensure optimal performance and avoid out-of-memory (OOM) errors, we recommend the following resources for this integration:
- CPU Limit:
800m - CPU Request:
100m - Memory Limit:
1Gi - Memory Request:
1Gi
Set resource values
helm install my-integration port-labs/port-ocean \
# ... other parameters
--set resources.limits.cpu=800m \
--set resources.limits.memory=1Gi \
--set resources.requests.cpu=100m \
--set resources.requests.memory=1Gi
- GitHub
- Jenkins
- Azure DevOps
- GitLab
- Go to the BitbucketCloud Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitHub Actions secret |
|---|---|---|---|
port_client_id | Your Port client ID (How to get the credentials). | ✓ | ✓ |
port_client_secret | Your Port client secret (How to get the credentials). | ✓ | ✓ |
port_base_url | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
bitbucket_workspace | The workspace you want to retrieve git objects from. | ✓ | ✓ |
bitbucket_workspace_token | The workspace token(s) for the Bitbucket Cloud account (can be a single token or comma-separated string of multiple tokens). Recommended for Premium accounts. | ✗ | ✓ |
bitbucket_user_scoped_token | The user-scoped token for the Bitbucket Cloud account. Replaces app password. Required for file kind (unless using existing app password). Works in free Bitbucket environments. | ✗ | ✓ |
bitbucket_user_email | The email address for user-scoped token authentication. Required when using BITBUCKET_USER_SCOPED_TOKEN. | ✗ | ✗ |
bitbucket_username | The username for app password authentication. Required when using BITBUCKET_APP_PASSWORD (deprecated). | ✗ | ✗ |
initialize_port_resources | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
integration_identifier | The identifier of the integration that will be installed. | ✗ | ✗ |
send_raw_data_examples | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Your Jenkins agent must be able to run Docker commands.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a Jenkins credential (Secret Text) |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The workspace you want to retrieve git objects from. | ✓ | ✓ |
OCEAN__ | The workspace token(s) for the Bitbucket Cloud account (can be a single token or comma-separated string of multiple tokens). Recommended for Premium accounts. | ✗ | ✓ |
OCEAN__ | The user-scoped token for the Bitbucket Cloud account. Replaces app password. Required for file kind (unless using existing app password). Works in free Bitbucket environments. | ✗ | ✓ |
OCEAN__ | The email address for user-scoped token authentication. Required when using BITBUCKET_USER_SCOPED_TOKEN. | ✗ | ✗ |
OCEAN__ | The username for app password authentication. Required when using BITBUCKET_APP_PASSWORD (deprecated). | ✗ | ✗ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a Jenkinsfile pipeline file:Jenkins pipeline (click to expand)
Prerequisites
- Your Azure Devops agent should be able to run docker commands. Learn more about agents here.
- You must have permissions to create and manage Azure DevOps variable groups for storing credentials.
Set up your credentials
- Create a Variable Group: Name it port-ocean-credentials.
- Store the required variables (see the table below).
- Authorize Your Pipeline:
-
Go to "Library" -> "Variable groups."
-
Find port-ocean-credentials and click on it.
-
Select "Pipeline Permissions" and add your pipeline to the authorized list.
-
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as an Azure DevOps pipeline variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The workspace you want to retrieve git objects from. | ✓ | ✓ |
OCEAN__ | The workspace token(s) for the Bitbucket Cloud account (can be a single token or comma-separated string of multiple tokens). Recommended for Premium accounts. | ✗ | ✓ |
OCEAN__ | The user-scoped token for the Bitbucket Cloud account. Replaces app password. Required for file kind (unless using existing app password). Works in free Bitbucket environments. | ✗ | ✓ |
OCEAN__ | The email address for user-scoped token authentication. Required when using BITBUCKET_USER_SCOPED_TOKEN. | ✗ | ✗ |
OCEAN__ | The username for app password authentication. Required when using BITBUCKET_APP_PASSWORD (deprecated). | ✗ | ✗ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a azure-pipeline.yml pipeline file:Azure pipeline (click to expand)
- Go to the BitbucketCloud Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitLab CI/CD variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The workspace you want to retrieve git objects from. | ✓ | ✓ |
OCEAN__ | The workspace token(s) for the Bitbucket Cloud account (can be a single token or comma-separated string of multiple tokens). Recommended for Premium accounts. | ✗ | ✓ |
OCEAN__ | The user-scoped token for the Bitbucket Cloud account. Replaces app password. Required for file kind (unless using existing app password). Works in free Bitbucket environments. | ✗ | ✓ |
OCEAN__ | The email address for user-scoped token authentication. Required when using BITBUCKET_USER_SCOPED_TOKEN. | ✗ | ✗ |
OCEAN__ | The username for app password authentication. Required when using BITBUCKET_APP_PASSWORD (deprecated). | ✗ | ✗ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Configuration
Port integrations use a YAML mapping block to ingest data from the third-party api into Port.
The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
Default mapping configuration
This is the default mapping configuration for this integration:
Default mapping configuration (click to expand)
resources:
- kind: project
selector:
query: 'true'
port:
entity:
mappings:
identifier: .uuid | gsub("[{-}]"; "")
title: .name
blueprint: '"bitbucketProject"'
properties:
private: .is_private
description: .description
type: .type
url: .links.html.href
- kind: repository
selector:
query: 'true'
includedFiles:
- README.md
port:
entity:
mappings:
identifier: .name
title: .name
blueprint: '"bitbucketRepository"'
properties:
url: .links.html.href
defaultBranch: .mainbranch.name
readme: .__includedFiles["README.md"]
relations:
project: .project.uuid | gsub("[{-}]"; "")
- kind: pull-request
selector:
query: 'true'
port:
entity:
mappings:
identifier: .destination.repository.name + (.id|tostring)
title: .title
blueprint: '"bitbucketPullRequest"'
properties:
creator: .author.display_name
assignees: '[.participants[].user.display_name]'
reviewers: '[.reviewers[].user.display_name]'
status: .state
createdAt: .created_on
updatedAt: .updated_on
link: .links.html.href
relations:
repository: .destination.repository.name
Mapping & selectors per resource
Use the explorer below to view the mapping and blueprint definition for each resource type. For additional resources and advanced configurations, see the examples page.
Set up live events
This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.
Note that different events are supported depending on the resource type.
repository:createdrepository:updatedrepository:pushpullrequest:createdpullrequest:updatedpullrequest:approvedpullrequest:unapprovedpullrequest:fulfilledpullrequest:rejected- Hosted by Port
- Self-hosted
Live events base URL
For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.
Call the endpoint with your integration's identifier:
curl -X GET \
'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
-H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:
- EU (app.port.io) →
https://api.port.io - US (app.us.port.io) →
https://api.us.port.io
In the response, look for the following fields under spec.appSpec:
{
"spec": {
"appSpec": {
"liveEventsUuid": "abcdefghijk",
"liveEventsIngestHostname": "ingest.ocean.getport.io"
}
}
}
Combine them to build the live events base URL:
https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>
For example, with the values above, the live events base URL is:
https://ingest.ocean.getport.io/live-events/abcdefghijk
This is the same URL configured for the integration.
BaseUrl & webhook configuration
To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Bitbucket Cloud integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.
- If Bitbucket Cloud and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
For Kubernetes deployments, create a service to expose the integration pod and use the service URL asliveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient. - If Bitbucket Cloud is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Bitbucket Cloud can reach.
If you're running high volumes of live events in a self-hosted deployment and want better reliability, event durability, or horizontal scalability, you can optionally set up Port's dedicated live events infrastructure. See live events at scale for details.
If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.
To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.
Examples
Refer to the examples page for practical configurations and their corresponding blueprint definitions.
Relevant Guides
For relevant guides and examples, see the guides section.
GitOps
Port's Bitbucket integration also provides GitOps capabilities, refer to the GitOps page to learn more.
Advanced
For advanced configuration options and use cases, refer to the advanced page.