Integration with GitLab

This integration is a specific case of Integrations with external systems.

Allure TestOps integration with GitLab is bidirectional, and Gitlab can be uses as CI system and as an issue tracker, this means you can do the following:

• CI: Upload test results from a GitLab pipeline (GitLab > Allure TestOps).
• CI: Trigger a GitLab pipeline (Allure TestOps > GitLab).
• Issue tacker: link test cases to GitLab issues.
• Issue tacker: link Launches to GitLab issues.
• Issue tacker: create bug reports in GitLab from Allure TestOps defects.

Uploading the test results from GitLab

To upload test results from GitLab you need to use allurectl.

The upload process requires authentication of allurectl in Allure TestOps, which requires the generation of API token on Allure TestOps side.

Authenticate GitLab build jobs

Authentication token

API token on Allure TestOps side could be generated for a real user, i.e. a person who uses Allure TestOps, or for a dedicated service account you need to create.

This API token will be used by allurectl running in a GitLab pipeline for the authentication on Allure TestOps server.

1. Log in to Allure TestOps with the account you are going to use to upload test results.
2. Go to the user's profile.

3. In the section API tokens click a blue button that says Create.
4. Name your API token and click Submit. Always give meaningful names to all the configuration parameters.

Allure will randomly generate the token and show you in the modal window.

5. Copy the token and save it in a safe place as it cannot be retrieved by Allure TestOps means.

Configuration of a GitLab project for the test results upload

Add your Allure server instance information to Gitlab' configuration

1. Navigate to CI/CD project settings

   

2. Navigate to Variables section

3. Create 3 variables as shown below

   1. ALLURE_ENDPOINT - Allure TestOps URL (for example: http://testops.company.com).
   2. ALLURE_TOKEN - Allure TestOps token created in the previous steps.
   3. ALLURE_PROJECT_ID - Allure TestOps project ID to which you are going to upload the results.

To upload the test results to a project in Allure TestOps the end user used to create API token must be explicitly added to the said project with at least Write permissions.

Build jobs

Single job pipeline

stages:
  - test

variables:
  ALLURE_LAUNCH_NAME: "${CI_PROJECT_NAME} - ${CI_COMMIT_SHORT_SHA}"
  ALLURE_LAUNCH_TAGS: "${CI_COMMIT_REF_NAME}, gitlab, demo, pytest, skip-live-doc, ignore"
  ALLURE_RESULTS: "./allure-results"
  TESTS_ENDPOINT: "https://pytest.never.never.never.give.up"
  TESTS_BROWSER: "firefox"
  TESTS_BRANCH: ${CI_COMMIT_REF_NAME}

test:
  image: python:3.9.1
  stage: test
  before_script:
    - wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -O ./allurectl
    - chmod +x ./allurectl
    - pip install pytest allure-pytest
  script:
    - ./allurectl watch -- pytest --alluredir=${ALLURE_RESULTS} || true

Second condition for the selective (re)run is the support of this feature in the Allure FrameWork adaptor for your test framework.

Multi-job pipeline

Standard and the only supported workflow for the multi-jobs pipelines is to send all the test results fro, a pipeline to a single launch.

stages:
  - unit
  - func

variables:
  ALLURE_LAUNCH_NAME: "${CI_PROJECT_NAME} - ${CI_COMMIT_SHORT_SHA}"
  ALLURE_LAUNCH_TAGS: "${CI_COMMIT_REF_NAME}, gitlab, multijob, fake-results"
  ALLURE_RESULTS: "allure-results"
  TESTS_ENDPOINT: "https://never.never.never.let.you.down"
  TESTS_BROWSER: "firefox"
  TESTS_BRANCH: ${CI_COMMIT_REF_NAME}

unit-tests:
  image: python:3.9.1  
  stage: unit
  before_script:
    - wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -O ./allurectl
    - chmod +x ./allurectl
    - chmod +x ./tests1.sh
    - ls -l $ALLURE_RESULTS || true

  script:
    - ./allurectl watch -- ./tests1.sh

func-test:
  image: python:3.9.1
  stage: func
  before_script:
    - wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -O ./allurectl
    - chmod +x ./allurectl
    - chmod +x ./tests2.sh
  script:
    - ./allurectl watch -- ./tests2.sh

Gathering environment information from GitLab

When we say environment we consider the context of a pipeline or context of a job inside a pipeline.

Context is usually stored in the environment variables (predefined Gitlab variables or user-defined ones) which can be used in Allure TestOps to distinguish results received from different jobs (here we can use predefined variables) or for different test environmens (here we use the information about a application under test, browser used and so on, i.e. data you pass to your tests).

Environment information can be used to

• filter the test results generated with this environment information, e.g. you can filter out the test results executed using a certain browser name or executed in certain job of a pipeline
• use the collected information to trigger CI pipelines with certain environment parameters

Preconditions

Environment variables need to be created in the Environment section on the Global level, then they can be used in projects to map pipelines' env data to them.

To properly collect environment variables from GitLab, first you must understand what environment data you have in your pipeline.

1. Go to pipeline Editor in Gitlab.

2. after allurectl execution add printenv command

The command printenv can be deleted later on.

Now, when you start the pipeline, the pipeline execution console will display all environment variables, so you can create mapping in TestOps.

For example we will add the mapping for Branch variable created on the global level (by an admin in Administration section).

1. Go to Project > Settings > Environment and click Create.

1. Input variable from Gitlab to Mapping Key field.
2. In the drop-down list select the Environment variable that was created on the Global level for mapping.

6. Click Submit.

Now, if you start the pipeline, you will see the value of the added variable on the page with Launches in the Environments section.

Job and its configuration

Job is an Allure TestOps entity linking your Allure TestOps project with the pipeline where you send the test results from.

Job is created by Allure TestOps automatically after the first test results upload from a pipeline. Automatically created job requires configuration.

The configuration of the job for the triggering of the GitLab workflows is only possible when the integration with GitLab has been completed.

Setting up the integration with GitLab

Preconditions

1. You have ROLE_ADMIN authority to configure Allure TestOps instance on the global level.
2. You have GitLab access token.
   • either personal access token
   • or project access token

How to generate GitLab access token

• Log into GitLab and in the upper-right corner click on your avatar, select Edit profile.
• Select Access Tokens in the User Settings menu (https://gitlab.com/-/profile/personal_access_tokens).
• Create personal Access token:

1. Enter Token name Allure.
2. Enter the token Expiration date that you need.
3. Select Scopes granted to the token: api, read_api.
4. Click Create personal access token.

Enabling Gitlab integration in Allure TestOps

1. Go to User menu > Administration > Integrations.
2. In the upper-right corner click Add integration.
3. Search for GitLab.
4. Click on the GitLab banner.
5. Provide the name of integration.
   • URL of your GitLab without http(s):// might be a good idea for the name.
6. Provide the GitLab URL to the Endpoint field.
   • for example https://gitlab.com
   • or the URL of your GitLab on-premises installation without any context paths, e.g. https://our-cool-gitab.internal
7. Finalize by clicking Add integration.

Next you'll see the following screen:

Testing connection

1. Click Test connection.
2. Enter your Token for access (generated in Gitlab).
3. Click Test connection.
4. After a successful connection test, click Save changes.

Project level integration

Preconditions

1. GitLab integration added on Global level by Allure TestOps admin.
2. You are Project Owner.

Adding Gitlab integration to a project

1. Click on Settings > Integrations.
2. Click Add integration on integration you or admin created at Global level.

3. In the opened window click Add projects and enter the ID of the GitLab project.
   • ID of GitLab project would be required if you are using GitLab as an issue tracker as well.

🔎 How to find GitLab project ID.

4. Enter your Token for access (generated in Gitlab).

5. Click Test connection.
6. After a successful connection test, click Add integration.

Trigger GitLab pipelines from TestOps

Preconditions

1. You need to have integration with GitLab added on the level of your project.
2. Job must be created in your project
   • for a job to be created in Allure TestOps just execute your pipeline once from GitLab and close the created launch
3. Integration need to be added to the Job's configuration.
4. Job must be allowed to trigger pipelines.

The following objects will be created in Allure TestOps during test results upload:

A new launch with the test results.

As soon as first launch created Allure Test also automatically creates a Job with the parameters received from the pipeline.

After closing a Launch you will see all your test cases created in the Test cases section of your project.

Job final configuration

To trigger the pipelines execution from Allure TestOps a job must be properly configured.

1. Go to the Jobs page.
2. Open the Configure menu of the created job.

3. In Configure settings fill the following
   1. Name,
   2. Build server
   3. Allow the job to be used to run tests
   4. and add the job's parameters you want to pass to your pipeline

4. Click Submit.

Now, you have the job which can be used for the pipeline triggering.

Triggering GitLab pipelines from Allure TestOps

Job can be used to trigger a pipeline from several places:

1. Directly from the Jobs section (see the image above)
2. from the list of test cases by requesting the run of test cases

• select test cases to run
• use the bulk action Run

3. From the test plans section by requesting a test plan execution

4. From Rerun actions of launches

5. From Rerun actions of test results