> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Bitbucket Cloud

BitBucket iconBitBucket icon
Loading version...

Port's Bitbucket integration allows you to model Bitbucket cloud resources in your software catalog and ingest data into them.

Supported resources External link iconProjectRepositoryPull RequestFolderFile

Core support

Live eventsSee supported resources
Bitbucket Server (Self-Hosted)

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​

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
    • Required scopes:
      • workspace: read
      • project: read
      • repository: read
      • pullrequest: read
      • webhooks: read and write

  • 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
    • Required scopes:
      • workspace: read
      • project: read
      • repository: read
      • pullrequest: read
      • webhooks: read and write
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.


Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

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.

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>'
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

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.

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.