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.
- Log in to Allure TestOps with the account you are going to use to upload test results.
- Go to the user's profile.
- In the section API tokens click a blue button that says Create.
- 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.
- 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
Navigate to CI/CD project settings
Navigate to Variables section
Create 3 variables as shown below
ALLURE_ENDPOINT
- Allure TestOps URL (for example:http://testops.company.com
).ALLURE_TOKEN
- Allure TestOps token created in the previous steps.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_TESTPLAN_PATH: "./testplan.json"
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:
- echo ${ALLURE_USER_USED}
- ./allurectl --version
- ./allurectl job-run plan --output-file ${ALLURE_TESTPLAN_PATH}
- ./allurectl watch -- pytest --alluredir=${ALLURE_RESULTS} || true
- ./allurectl job-run plan --output-file ${ALLURE_TESTPLAN_PATH}
is required to make selective (re)run of tests possible.
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_TESTPLAN_PATH: "./testplan.json"
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 job-run plan --output-file ${ALLURE_TESTPLAN_PATH}
- ./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 job-run plan --output-file ${ALLURE_TESTPLAN_PATH}
- ./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.
- Go to pipeline Editor in Gitlab.
- after
allurectl
execution addprintenv
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).
- Go to Project > Settings > Environment and click Create.
- Input variable from Gitlab to Mapping Key field.
- In the drop-down list select the Environment variable that was created on the Global level for mapping.
- 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 GitHub workflows is only possible when the integration with GitHub has been completed.
Setting up the integration with GitLab
Preconditions
- You have
ROLE_ADMIN
authority to configure Allure TestOps instance on the global level. - 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:
- Enter Token name
Allure
. - Enter the token Expiration date that you need.
- Select Scopes granted to the token:
api
,read_api
. - Click Create personal access token.
Enabling Gitlab integration in Allure TestOps
- Go to User menu > Administration > Integrations.
- In the upper-right corner click Add integration.
- Search for GitLab.
- Click on the GitLab banner.
- Provide the name of integration.
- URL of your GitLab without
http(s)://
might be a good idea for the name.
- URL of your GitLab without
- 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
- for example
- Finalize by clicking Add integration.
Next you'll see the following screen:
Testing connection
- Click Test connection.
- Enter your Token for access (generated in Gitlab).
- Click Test connection.
- After a successful connection test, click Save changes.
Project level integration
Preconditions
- GitLab integration added on Global level by Allure TestOps admin.
- You are
Project Owner
.
Adding Gitlab integration to a project
- Click on Settings > Integrations.
- Click Add integration on integration you or admin created at Global level.
- 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.
- Enter your Token for access (generated in Gitlab).
- Click Test connection.
- After a successful connection test, click Add integration.
Trigger GitLab pipelines from TestOps
Preconditions
- You need to have integration with GitLab added on the level of your project.
- 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
- Integration need to be added to the Job's configuration.
- 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.
- Go to the Jobs page.
- Open the Configure menu of the created job.
- In Configure settings fill the following
- Name,
- Build server
- Allow the job to be used to run tests
- and add the job's parameters you want to pass to your pipeline
- 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:
- Directly from the Jobs section (see the image above)
- from the list of test cases by requesting the run of test cases
- select test cases to run
- use the bulk action Run
- From the test plans section by requesting a test plan execution
- From Rerun actions of launches
- From Rerun actions of test results