1. Docs
  2. Integrations
  3. Version Control
  4. Bitbucket

Bitbucket

    Pulumi Cloud integrates with Bitbucket Cloud to post pull request previews, deploy infrastructure on push, create ephemeral review stacks, and report commit statuses — the same capabilities available with GitHub, GitLab, and Azure DevOps. Once configured, the integration automatically registers webhooks on your Bitbucket workspace and manages authentication for you.

    Installation and configuration

    To set up the Bitbucket integration, you must be an org admin in Pulumi Cloud and have appropriate permissions in your Bitbucket workspace.
    1. Sign in to your Pulumi account.
    2. Navigate to Management > Version control.
    3. Select Add account and choose Bitbucket, then follow the prompts to authorize with Bitbucket.
    4. Select the Bitbucket workspace you want to integrate with and configure your integration settings.

    Pulumi automatically registers webhooks on your Bitbucket workspace. No manual webhook configuration is required.

    Authentication methods

    Pulumi supports two authentication methods depending on your Bitbucket plan:

    • Personal OAuth (all workspaces including Free): Uses the logged-in user’s Bitbucket OAuth token. The user must have appropriate permissions in the target workspace. This is the default option for free Bitbucket workspaces.
    • Workspace Token (Premium workspaces): An admin generates a workspace access token in Bitbucket and pastes it into Pulumi Cloud. The token requires the following scopes:
      ScopePurpose
      repository:adminCreate new repositories from project templates
      repository:writePush template code into repositories
      pullrequest:writePost pull request comments
      webhookRegister webhooks for deployment triggers

    If your workspace does not support workspace access tokens, Pulumi Cloud prompts you to use personal OAuth for organization authentication instead.

    Individual user setup

    Separately from the org-level integration, individual users can complete an OAuth flow under Management > Version control to grant Pulumi access to their Bitbucket account. This is used for features like Neo Agent repository creation on the user’s behalf and does not create webhooks.

    To remove your individual identity, select your identity on the integration card and choose Remove Identity.

    Integration settings

    After creating an integration, you can configure pull request behavior. Toggle these settings per integration:

    SettingDefaultDescription
    Pull request commentsEnabledPost deployment status and resource changes as comments on Bitbucket pull requests
    Neo summaries for pull request commentsEnabledInclude AI-generated summaries of infrastructure changes in pull request comments (requires AI Agents to be enabled for your organization)
    Detailed diff for pull request commentsEnabledShow property-level before/after diffs for changed resources in pull request comments

    To delete an integration, select Delete Integration on the integration card. This removes the webhook from your Bitbucket workspace and disconnects all stacks using that integration.

    Capabilities

    Pull request comments

    Pulumi automatically posts comments on pull requests with the results of any stack changes. This includes a summary of how many resources were created, updated, or deleted, with a link to the full details in Pulumi Cloud. When enabled, comments also include a collapsible detailed diff and an AI-generated explanation from Neo.

    Comments are idempotent: updates to the same stack edit the existing comment rather than creating a new one. Draft pull requests are treated identically to regular pull requests.

    For review stacks, comments show the review stack status and outputs instead of a standard preview summary.

    Commit status checks

    Pulumi posts commit status checks to Bitbucket on every deployment, for both push and pull request events. Statuses include a link back to the deployment in Pulumi Cloud.

    Push-to-deploy

    Push-to-deploy automatically runs pulumi up when a commit is pushed to a configured branch, most commonly the default branch. Enable this under Stack > Settings > Deploy by toggling Deploy on push. See the push-to-deploy documentation for setup instructions.

    You can use path filters to limit deployments to commits that change files matching specific glob patterns (e.g., infrastructure/**).

    Review stacks

    Review stacks are ephemeral cloud environments created automatically every time a pull request is opened, powered by Pulumi Deployments. Open a pull request, and Pulumi Deployments stands up a stack with your changes and posts a pull request comment with the outputs. Merge or close the pull request, and Pulumi Deployments destroys the stack and frees the associated resources.

    To enable review stacks, toggle Pull request template under Stack > Settings > Deploy on the stack you want to use as a template.

    Environment variables

    Pulumi injects the following environment variables during Bitbucket-triggered deployments:

    VariableSet whenValue
    PULUMI_CI_BRANCH_NAMEPush and pull request eventsBranch name
    PULUMI_PR_NUMBERPull request eventsPull request ID (number)
    PULUMI_CI_PULL_REQUEST_SHAPull request eventsFull commit SHA

    New project wizard

    The New Project Wizard supports Bitbucket as a VCS provider. When the Bitbucket integration is configured, you can:

    • Create new Bitbucket repositories in your integrated workspace
    • Select an existing Bitbucket repository and branch
    • Choose any deployment method: CLI, Pulumi Deployments (no-code), or Pulumi Deployments (VCS-backed)

    When using the VCS-backed deployment method, the wizard configures deploy-on-push, pull request previews, and review stacks automatically.

    Bitbucket repositories cannot be used as template sources at this time. You can still use templates from other configured VCS providers (such as GitHub or GitLab) or from the Pulumi private registry.

    CI integration

    The Pulumi Bitbucket integration posts results back to Bitbucket regardless of which CI/CD system triggers the run. You can also run Pulumi commands directly in Bitbucket Pipelines. See the Bitbucket Pipelines guide for setup instructions and example pipeline configurations.

    OIDC authentication

    Use Bitbucket Pipelines’ built-in OIDC tokens to authenticate with Pulumi Cloud without storing long-lived credentials as pipeline variables. See Configuring OpenID Connect for Pulumi for configuration details.

    Troubleshooting

    Pull request comments not appearing

    If comments aren’t appearing on your pull requests, verify that:

    1. The Bitbucket integration is connected and shows a valid status under Management > Version control.
    2. The webhook exists on your Bitbucket workspace. Navigate to your workspace’s Settings > Webhooks and look for the Pulumi webhook endpoint.
    3. The stack is associated with the correct Bitbucket repository and branch.

    Integration shows as disconnected

    If the integration card shows an invalid or disconnected status, delete the integration and re-create it by following the installation steps.

    Deployments not triggering

    If deployments aren’t triggering on push or pull request events:

    1. Verify deployment settings are enabled under Stack > Settings > Deploy.
    2. Check that the branch matches your configured deployment branch.
    3. If using path filters, confirm that the changed files match your glob patterns.