Skip to main content

Check out Port for yourself ➜ 

Installation

Loading version...

This page details how to install Port's Bitbucket Cloud integration (powered by the Ocean framework). It outlines the following steps:

  • How to create a workspace token/app password to give the integration permissions to query your Bitbucket Cloud account.
  • How to configure and customize the integration before deploying it.
  • How to deploy the integration in the configuration that fits your use case.

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​

App Password Deprecation

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

  • User-Scoped Token (Replacement for App Passwords)

    • Required for new setups using the file kind (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

  • App Password (Deprecated)

    • ⚠️ Being phased out by Bitbucket - migrate to user-scoped tokens
    • Requires username and app password combination
    • Create an app password
Use of dedicated accounts and tokens

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.

All authentication methods should have read permission scope for each of the supported resources you want to ingest into Port and a read and write permission scope for webhooks.

Deploy the integration​

Choose one of the following installation methods:
Not sure which method is right for your use case? Check the available installation methods.

Using this installation option means that the integration will be hosted by Port, with a customizable resync interval to ingest data into Port.

Live event support

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Supported live event triggers

Repository:

  • repository:created
  • repository:updated
  • repository:push

Pull Request:

  • pullrequest:created
  • pullrequest:updated
  • pullrequest:approved
  • pullrequest:unapproved
  • pullrequest:fulfilled
  • pullrequest:rejected
Self-hosted installation

Alternatively, you can install the integration using the Self-hosted method to update Port in real time using webhooks.

Installation

To install, follow these steps:

  1. Go to the Data sources page of your portal.

  2. Click on the + Data source button in the top-right corner.

  3. Click on the relevant integration in the list.

  4. Under Select your installation method, choose Hosted by Port.

  5. Configure the integration settings and application settings as you wish (see below for details).

Application settings

Every integration hosted by Port has the following customizable application settings, which are configurable after installation:

  • Resync interval: The frequency at which Port will ingest data from the integration. There are various options available, ranging from every 1 hour to once a day. If a sync is still in progress when the next one is due, the new sync will be skipped (up to 24 hours delay).
    This ensures that all kinds are fully synchronized and that cleanup of stale entities always takes place at the end of each sync.

  • Send raw data examples: A boolean toggle (enabled by default). If enabled, raw data examples will be sent from the integration to Port. These examples are used when testing your mapping configuration, they allow you to run your jq expressions against real data and see the results.

Integration settings

Every integration has its own tool-specific settings, under the Integration settings section.
Each of these settings has an ⓘ icon next to it, which you can hover over to see a description of the setting.

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.

Limitations

  • The maximum time for a full sync to run is based on the configured resync interval. For very large amounts of data where a resync operation is expected to take longer, please use a longer interval.

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:

54.73.167.226  
63.33.143.237  
54.76.185.219