Bitbucket Cloud

Loading version...

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

Supported resources ProjectRepositoryPull RequestFolderFile

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 & examples 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.

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.