Bitbucket CI

Bitbucket CI integration uploads test results from a Bitbucket pipeline to Allure TestOps using allurectl, and lets TestOps trigger Bitbucket pipelines.

Before you begin

• The URL of your TestOps instance and the numeric project ID.
• A TestOps API token for the upload path.
• A Bitbucket account and API token for the trigger path.

1. Send results from Bitbucket to TestOps

Create the TestOps token

1. In Allure TestOps, click your avatar and open API Tokens.
2. Click + Token.
3. Enter a name for the token, for example Token for Bitbucket, and click Create.
4. Copy the generated token. Save it in a secure location — it cannot be retrieved after you close the dialog.

Variables required by allurectl

Add the following environment variables to the Bitbucket pipeline that runs the tests:

Set ALLURE_ENDPOINT at workspace level

If you have a single TestOps instance, set ALLURE_ENDPOINT once at the Bitbucket workspace level so all pipelines inherit it.

Open workspace settings at https://bitbucket.org/{ORGNAME}/workspace/settings/addon/admin/pipelines/account-variables and add ALLURE_ENDPOINT with the value of your TestOps URL.

Add variables via the pipeline UI

Add ALLURE_TOKEN, ALLURE_PROJECT_ID, and ALLURE_RESULTS at the pipeline configuration level:

1. In the Bitbucket repository, open Source and click bitbucket-pipelines.yml.

2. Click Edit, then Edit again.

3. Expand the Configure tab and find Add variables.

4. Add the following variables:

   • ALLURE_TOKEN — Secured
   • ALLURE_PROJECT_ID — not secured
   • ALLURE_RESULTS — not secured

   

Configure bitbucket-pipelines.yml

Declare ALLURE_LAUNCH_NAME and ALLURE_LAUNCH_TAGS in the pipeline's variables block so TestOps can override them at trigger time. Use allurectl watch to wrap the test command:

image: gradle:8.10-jdk21

pipelines:
  custom:
    test:
      - variables:
          - name: ALLURE_LAUNCH_NAME
            default: ""
          - name: ALLURE_LAUNCH_TAGS
            default: "bitbucket, junit5"

      - step:
          name: Run tests
          script:
            - wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -O ./allurectl
            - chmod +x ./allurectl
            - ALLURE_LAUNCH_NAME="${BITBUCKET_REPO_FULL_NAME} - $BITBUCKET_BUILD_NUMBER"
            - ./allurectl watch -- gradle --no-daemon clean test

The custom: section with a named pipeline (test: in this example) is required for triggering the pipeline from TestOps via API. The variables: block must include at minimum ALLURE_LAUNCH_NAME and ALLURE_LAUNCH_TAGS.

2. Pass environment parameters to TestOps

If tests run with parameters such as browser, host, or branch, add those as pipeline variables and map them in TestOps so launches show the environment they ran on.

Add parameters to the pipeline

Extend the variables block with the parameters you want to track:

    test:
      - variables:
          - name: ALLURE_LAUNCH_NAME
            default: ""
          - name: ALLURE_LAUNCH_TAGS
            default: "bitbucket, junit5"
          - name: PRODUCT_VERSION
            default: "1.23"
          - name: TESTS_BROWSER
            default: "chrome"

When running the pipeline manually from Bitbucket, the variables appear in the run dialog:

Set ALLURE_LAUNCH_NAME explicitly in the script so the launch name includes build context:

- ALLURE_LAUNCH_NAME="${BITBUCKET_REPO_FULL_NAME} - $BITBUCKET_BUILD_NUMBER"

Map parameters in the TestOps project

allurectl forwards all pipeline environment variables to TestOps. To surface them as launch environment labels, map them in the project settings:

1. In the project, open Settings → Environment.

2. For each parameter, click + Create:

   • Mapping key — the Bitbucket variable name, for example TESTS_BROWSER.
   • Environment variable — the global parameter name created by the administrator in Administration → Environment.

3. Click Submit.

   

Run the pipeline once from Bitbucket. When the launch appears in TestOps, the mapped variables should show as environment labels.

3. Let TestOps trigger Bitbucket pipelines

Add the global Bitbucket integration

An instance administrator should:

1. Open Administration → Integrations.
2. Click + Add integration.
3. Search for Bitbucket and click it.
4. Fill in the fields:
   • Name — a recognizable name, for example bitbucket.org.
   • Endpoint — the Bitbucket URL, for example https://bitbucket.org.
5. Click Add integration.

Create a Bitbucket API token

Tokens are supported starting from Allure TestOps Release 25.4.1.

1. Open your Atlassian account at https://id.atlassian.com/manage-profile/email and copy your email address.
2. Go to Security → API tokens at https://id.atlassian.com/manage-profile/security/api-tokens and click Create API token with scopes.
3. Enter a name for the token.
4. Grant the following scopes:
   1. read:me
   2. read:user:bitbucket
   3. read:repository:bitbucket
   4. read:pipeline:bitbucket
   5. write:pipeline:bitbucket
   6. write:repository:bitbucket
5. Copy the generated token.

Add the integration to the TestOps project

You need to be a project owner to configure these settings.

1. In Allure TestOps, open the project and go to Settings → Integrations.
2. Under Available integrations, find the Bitbucket integration and click Add integration.
3. Enter your email address as the username and the Bitbucket API token.
4. Click Test connection.
5. Click Add integration.

Configure the job in TestOps

After the first successful upload, TestOps creates the job automatically:

1. Open Jobs, click ⋯ next to the job, and select Configure.

2. Set Build server to the Bitbucket integration added in the project settings.

3. Enable Job can be used to run tests.

4. Map environment variables from the pipeline to global environment variable names.

   

5. Click Submit.

Two variables require special handling:

Branch — must be mapped to the global Branch environment variable. The default value sets which branch the pipeline runs on when triggered from TestOps.

CustomName — does not map to a global variable, but requires a default value. Set it to the name of the custom pipeline in bitbucket-pipelines.yml that TestOps should trigger.

Trigger a pipeline from TestOps

A TestOps-triggered build can be started from:

• Test cases — select cases and use the bulk Run action.
• Test results — select results and use ReRun.
• Test plans — click Run on a test plan.
• Jobs — click Run on a job.

To run with different parameters, open the job settings, click Add environment, set the values, and save. Multiple environments result in multiple pipeline runs that all upload to the same launch.

Related pages

• CI systems
• allurectl
• Jobs
• Environment
• Bitbucket work management