Connect Bitbucket

Prodgator connects to Bitbucket Cloud with OAuth. You sign in with Bitbucket, pick a workspace, and Prodgator adds one workspace webhook that reports Bitbucket Pipelines build statuses and pull request events for every repository in it.

RequirementsCopy Anchor Link

• On Bitbucket: admin of the workspace.
• In Prodgator: the admin role.

Connect a workspaceCopy Anchor Link

1. Open Admin Console > Integrations.
2. On the Bitbucket card, click Connect Bitbucket (or Connect another Bitbucket workspace).
3. Sign in to Bitbucket and grant access.
4. Pick the workspace. Only workspaces where you are an admin are listed.

The workspace then appears on the Bitbucket card.

The webhook Prodgator createsCopy Anchor Link

Bitbucket signs each delivery with the secret in the X-Hub-Signature header (sha256= followed by an HMAC-SHA256 of the body). Prodgator rejects deliveries whose signature does not match.

What you seeCopy Anchor Link

Each Bitbucket Pipelines build shows as a pipeline run, named after the build status. When you open a run, Prodgator reads its steps and step logs from the Bitbucket API with the connection's token.

Pull request gatesCopy Anchor Link

Prodgator gates Bitbucket pull requests with the same policies as GitHub pull requests: it posts a Prodgator Policies build status on each pull request's head commit, and a branch restriction makes Bitbucket wait for it. See Pull request gates for how to bind a policy and require the build.

What the connection needs:

• Pull requests: Read on the OAuth client, for reading pull requests and subscribing to their events. Connections made before pull request gates need to be connected again once to grant it; Bitbucket asks for consent on the next sign-in.
• Write access to the repository for the person who connected the workspace, for posting the build status.
• Pull requests: Write on the OAuth client, for the policy comment on each pull request. Without it the build status still works and the comment is left out.
• Repositories: Admin (optional) to read branch restrictions for the Merge protection section. Without it, Prodgator reads the pull request's merge checks, which tell the same for an open pull request.

Prodgator updates the webhook of an existing connection to add the pull request triggers on its own, sending the connection's stored secret again. If it cannot (for example, the token lacks Pull requests: Read), connect the workspace again.

Approve deployments from ProdgatorCopy Anchor Link

Bitbucket Cloud's API can start or stop a whole pipeline, but it cannot approve, resume or run a paused step: a trigger: manual step runs only from Bitbucket's own Run button. So Prodgator approves a Bitbucket deployment through the deployment step itself. Add the Prodgator pipe as the first command of the step with GATE: 'true':

- step:
    name: Deploy to production
    deployment: production
    max-time: 90
    oidc:
      audiences:
        - https://api.prodgator.io
    script:
      - pipe: prodgator/prodgator-pipe:<version>
        variables:
          GATE: 'true'
          GATE_TIMEOUT: '60'
      - ./deploy.sh

Gate mode needs a pipe release newer than 1.0.0: use the newest version in the changelog of the Prodgator pipe. Outside the pipe, npx @prodgator/report --gate does the same.

When the step starts, the pipe opens a gate in Prodgator for the step's deployment environment (it authenticates with the step's OIDC token) and waits:

1. The deployment shows on Gates > Awaiting approval as awaiting approval in Prodgator, and approvers are notified.
2. Someone approves or rejects it in Prodgator, or an enforce release policy bound to the environment decides it.
3. Approved: the pipe exits 0 and the rest of the step deploys. Rejected: the pipe exits 1 and the step stops with who rejected it and why.

The pipe fails closed. If it cannot reach Prodgator, the step is not a deployment step, or no decision comes within GATE_TIMEOUT minutes (default 60, at most 720), the step fails without deploying. Run the step again to open a new gate.

Things to know:

• The step runs, and uses build minutes, while it waits. Set its max-time above GATE_TIMEOUT.
• The gate needs no extra Bitbucket permission and no linked Bitbucket account: Prodgator sends nothing to Bitbucket, the step reads the decision. Existing connections work as they are.
• Bitbucket's deployment permissions (Premium) still decide who can start the step. The gate is an extra check inside it.
• A step that deployed while its gate was open or rejected (for example, after the pipe was removed) is recorded as Bypassed.

See Approve deployments for who can answer and how policies decide.

Check the connectionCopy Anchor Link

Push a commit to a repository in the workspace that has bitbucket-pipelines.yml. The build appears on the Pipelines page within a few seconds.

TroubleshootingCopy Anchor Link

"Nothing to connect". You are not an admin of any workspace. Ask a workspace admin for access, or ask them to connect Bitbucket from Prodgator. Bitbucket connects through Prodgator's sign-in with Bitbucket, so there is nothing to install in Bitbucket.

"Webhook not created". Prodgator could not add the workspace webhook. Check that you can manage webhooks in the workspace settings.

Builds missing. In Bitbucket open Workspace settings > Webhooks, find the Prodgator webhook and check its request history.

Pull requests missing. The webhook must have the pull request triggers listed above. If it has only the build status triggers, connect the workspace again so Prodgator can add them.

No Prodgator Policies build status. Open the pull request on the Pull Requests page: its latest evaluation names the reason (for example, Bitbucket refused the status because the connecting account cannot write to the repository, or the pull request comes from a fork).

LimitsCopy Anchor Link

• Prodgator approves only deployment steps that run the gate. Run trigger: manual steps, and steps Bitbucket's deployment permissions hold, in Bitbucket.
• Linking your own Bitbucket account in your profile is possible. Approvals do not need it, because Bitbucket records nothing for them.

DisconnectingCopy Anchor Link

Click the delete icon next to the workspace in Admin Console > Integrations. Prodgator deletes the webhook, revokes its token and removes the stored secrets.