Bitbucket Pipelines

QualityGate supports pull request and branch pipelines on Bitbucket Cloud. Bitbucket Data Center is not supported. The pipe image already contains the browser, so there is nothing to install.

1. Create the project

In the app, go to Projects → Create project → Bitbucket and enter:

• the repository as workspace/repository, as it appears in its URL;
• the repository UUID, shown under Repository settings, or printed by echo $BITBUCKET_REPO_UUID in any pipeline;
• the default branch and the allowed preview domains.

QualityGate accepts runs only from the repository with that UUID, so a renamed or re-created repository cannot impersonate it.

Create an API key named Bitbucket Pipelines on the project card and copy it. It is shown only once.

2. Add repository variables

Open Repository settings → Repository variables and add two Secured variables:

Variable	Value
QUALITYGATE_API_KEY	The project API key.
QUALITYGATE_BITBUCKET_TOKEN	A repository access token with the pullrequest:write scope. Only needed for comments.

3. Add the step

Download qualitygate.bitbucket-pipelines.yml from a QualityGate release. It contains the pipe image pinned by digest. Merge its step into your bitbucket-pipelines.yml:

definitions:
  steps:
    - step: &qualitygate
        name: QualityGate
        oidc:
          audiences:
            - https://api.qualitygate.dev
        script:
          - pipe: docker://ghcr.io/qualitygate/bitbucket-pipe@sha256:<digest from the release>
            variables:
              QUALITYGATE_API_KEY: $QUALITYGATE_API_KEY
              QUALITYGATE_URL: https://pr-${BITBUCKET_PR_ID}.preview.example.com
              QUALITYGATE_ID_TOKEN: $BITBUCKET_STEP_OIDC_TOKEN
              QUALITYGATE_BITBUCKET_TOKEN: $QUALITYGATE_BITBUCKET_TOKEN
              QUALITYGATE_BUNDLE: a11y
              QUALITYGATE_FAIL_ON: critical=0,serious=0

pipelines:
  pull-requests:
    '**':
      - step: *qualitygate
  branches:
    main:
      - step:
          <<: *qualitygate
          script:
            - pipe: docker://ghcr.io/qualitygate/bitbucket-pipe@sha256:<digest from the release>
              variables:
                QUALITYGATE_API_KEY: $QUALITYGATE_API_KEY
                QUALITYGATE_URL: https://www.example.com
                QUALITYGATE_ID_TOKEN: $BITBUCKET_STEP_OIDC_TOKEN
                QUALITYGATE_FAIL_ON: regression

The oidc block makes Bitbucket sign a short-lived identity token for the step, which you pass on as QUALITYGATE_ID_TOKEN. QualityGate checks that it was issued for your workspace and names the registered repository UUID.

The main branch step scans your production site and records the baseline that regression mode compares pull requests against. Pull requests are then compared page by page, whatever host their preview uses.

Variables

Pipes only receive the variables you list under variables, so add every option you use there.

Variable	Required	Default	Purpose
QUALITYGATE_API_KEY	Yes	none	Project API key.
QUALITYGATE_URL	Yes	none	Preview URL on an allowed domain.
QUALITYGATE_ID_TOKEN	Yes	none	Pass $BITBUCKET_STEP_OIDC_TOKEN.
QUALITYGATE_BITBUCKET_TOKEN	For comments	none	Repository access token with pullrequest:write.
QUALITYGATE_BUNDLE	No	a11y	See Bundles and checks.
QUALITYGATE_FAIL_ON	No	critical=0,serious=0	Limits or regression.
QUALITYGATE_WAIT_FOR_URL	No	true	Wait for the preview to answer before scanning.
QUALITYGATE_WAIT_TIMEOUT	No	120	Seconds to wait for the preview.
QUALITYGATE_COMMENT	No	true	Post or update the pull request comment. Set 'false' to skip it and the token.

Comments

Bitbucket does not render HTML in comments, so the pipe posts the same report with a plain “Scan details” section instead of a collapsible one. It updates its own comment on later runs and never edits anyone else’s.