TestOps logo
Try TestOps

CircleCI

CircleCI integration connects CircleCI pipelines to Allure TestOps: uploads test results during a pipeline run using allurectl, lets TestOps trigger CircleCI pipelines, and maps pipeline parameters to launch environments.

Before you begin

  • Permission to edit .circleci/config.yml.
  • The URL of the TestOps instance and the numeric TestOps project ID.
  • A TestOps API token for the upload path.
  • A CircleCI personal API token for the trigger path.

1. Send results from CircleCI 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 CircleCI, and click Create.
  4. Copy the generated token.

Add the token to CircleCI

  1. In CircleCI, open the project and click Project Settings in the top right corner.
  2. In the left menu, click Environment Variables.
  3. Click Add Environment Variable.
  4. Fill in the fields:
    • Name — ALLURE_TOKEN
    • Value — the API token copied from TestOps
  5. Click Add Environment Variable.

Update .circleci/config.yml

Keep the configuration on version 2.1, declare the ALLURE_JOB_RUN_ID and ALLURE_USERNAME pipeline parameters, and wrap the test command with allurectl watch:

version: 2.1

parameters:
  ALLURE_JOB_RUN_ID:
    type: string
    default: ""
  ALLURE_USERNAME:
    type: string
    default: ""

jobs:
  test:
    docker:
      - image: cimg/openjdk:17.0
    environment:
      ALLURE_ENDPOINT: https://testops.example.com
      ALLURE_PROJECT_ID: "1"
      ALLURE_RESULTS: build/allure-results
      ALLURE_JOB_RUN_ID: << pipeline.parameters.ALLURE_JOB_RUN_ID >>
      ALLURE_USERNAME: << pipeline.parameters.ALLURE_USERNAME >>
    steps:
      - checkout
      - run:
          name: Download allurectl
          command: curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl && chmod +x allurectl
      - run:
          name: Run tests
          command: ./allurectl watch -- ./gradlew clean test

workflows:
  test:
    jobs:
      - test

ALLURE_JOB_RUN_ID and ALLURE_USERNAME must always be declared as optional string parameters — they are part of the service contract TestOps uses when triggering runs.

If the job image does not include curl, use wget or bake allurectl into a custom Docker image.

Verify the upload

After the next pipeline run:

  1. In CircleCI, open the job log for the step that runs tests. Near the end of the log there should be a link to the TestOps launch.

    The link to the launch is in the pipeline run log.

  2. Open that launch in TestOps and confirm test results are present.

  3. Open one result and confirm it links back to the CircleCI job.

    The link to the CircleCI pipeline is at the bottom of the test results pane.

2. Let TestOps trigger CircleCI pipelines

Add the global CircleCI integration

An instance administrator should:

  1. Open Administration → Integrations.
  2. Click + Add integration.
  3. Select CircleCI.
  4. Fill in the fields:
    • Name — a recognizable name, for example CircleCI production.
    • Endpoint — the CircleCI URL, for example https://circleci.com/.
  5. If the CircleCI instance uses a self-signed SSL certificate, check Disable certificate validation.
  6. Click Add integration.

Create a CircleCI personal API token

  1. In CircleCI, click your avatar in the bottom left corner.
  2. In the left menu, click Personal API Tokens.
  3. Click Create New Token.
  4. Enter a Token Name, for example Token for Allure TestOps.
  5. Click Add API Token and copy the generated token.

Add CircleCI credentials to the TestOps project

  1. In TestOps, open the target project and go to Settings → Integrations.
  2. Under Available integrations, find the CircleCI integration and click Add integration.
  3. Enter the CircleCI token.
  4. Click Test connection. A "Connection established" message confirms the token is correct.
  5. Click Add integration.

Configure the job in TestOps

After the first successful upload, TestOps creates the CircleCI-backed job automatically:

  1. Open Jobs in the project.

  2. Click ⋯ next to the job and select Configure.

  3. Fill in the fields:

    • Name — a stable display name.
    • Build server — the global CircleCI integration added by the administrator.
    • Job can be used to run tests — enable to allow triggering from TestOps.
    • Parameters — see Section 3.

    The dialog allows to set job settings.

  4. Click Submit.

3. Pass parameters and branch values

CircleCI pipeline parameters let TestOps control values such as branch, browser, or target environment and make them visible on launches triggered outside TestOps.

Set default values in CircleCI

Add custom parameters to the global parameters block and expose them as environment variables in the job:

version: 2.1

parameters:
  ALLURE_JOB_RUN_ID:
    type: string
    default: ""
  ALLURE_USERNAME:
    type: string
    default: ""
  PRODUCT_VERSION:
    type: string
    default: "1.23"
  TESTS_BROWSER:
    type: string
    default: chrome

jobs:
  test:
    docker:
      - image: cimg/openjdk:17.0
    environment:
      ALLURE_ENDPOINT: https://testops.example.com
      ALLURE_PROJECT_ID: "1"
      ALLURE_RESULTS: build/allure-results
      ALLURE_JOB_RUN_ID: << pipeline.parameters.ALLURE_JOB_RUN_ID >>
      ALLURE_USERNAME: << pipeline.parameters.ALLURE_USERNAME >>
      PRODUCT_VERSION: << pipeline.parameters.PRODUCT_VERSION >>
      TESTS_BROWSER: << pipeline.parameters.TESTS_BROWSER >>
    steps:
      - checkout
      - run:
          name: Download allurectl
          command: curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl && chmod +x allurectl
      - run:
          name: Run tests
          command: ./allurectl watch -- ./gradlew clean test

workflows:
  test:
    jobs:
      - test

Add global environment names

An instance administrator should:

  1. Open Administration → Environment.

  2. For each parameter, click + Create, enter the name, and click Submit.

    Environment variable names are added in the Administration section.

Map parameters in the project

  1. In the project, open Settings → Environment.

  2. For each parameter, click + Create (or the edit icon if it already exists):

    • Mapping key — the CircleCI parameter name from the parameters block.
    • Environment variable — the global parameter name created by the administrator.

  3. Click Submit.

    Mapping environment variables is configured in the project settings.

Add parameters to the job

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

  2. In the Parameters section, click Add for each parameter:

    • Name — the CircleCI parameter name (matches the mapping key).
    • Value — the default value.
    • Environment Variable — the global parameter name.

    Multiple environment variables can be specified in the dialog.

  3. Click Submit.

If the project has multiple branches, add a Branch environment variable and map it to the CircleCI parameter that controls branch selection.

Troubleshooting

No results arrive in TestOps

Check:

  • ALLURE_TOKEN is set in CircleCI project settings;
  • ALLURE_ENDPOINT, ALLURE_PROJECT_ID, and ALLURE_RESULTS point to the expected TestOps project and results directory;
  • the job runs ./allurectl watch -- <test command>.

CircleCI uploads results but the run is not linked correctly

The ALLURE_JOB_RUN_ID and ALLURE_USERNAME pipeline parameters were not passed to the job environment. Check that both parameters are declared in the global parameters block and referenced in the job's environment block.

© Qameta Software Inc. All rights reserved.