Share this page

# GitLab CI integration

Integrate GitLab CI with OpenText Software Delivery Management, utilizing webhooks and secure credentials.

The integration enables you to receive and process pipeline events from GitLab, providing enhanced visibility and traceability for your CI/CD workflows.

In this topic:

## Supported features

The GitLab CI integration provides the following functionality within OpenText Software Delivery Management.

### Pipelines and builds

- Collect pipeline step results
- Run pipeline
- Run pipeline with parameters

### Hierarchy in topology

- Multi-branch pipeline
- Multiple spaces

### Test automation

- Run on-demand automated JUnit tests
- Run UFT One automated tests
- Run Cucumber automated tests

## Prerequisites

Before starting the integration, verify the following prerequisites:

- GitLab.com, GitLab dedicated, or self-managed GitLab version 18.8 and above
- Administrator access on space and workspace
- Administrator access to your GitLab projects
- (Optional) Ultimate GitLab license for group/instance-level features

## Configuration parameters

Configure the following parameters to support the GitLab integration. They can be set at the site or space level.

Parameter | Default | Description
--- | --- | ---
CI_INTEGRATION_GITLAB_INPUTS_ARTIFACT_NAME | N/A | Name of the artifact file containing parameters and values.
CI_INTEGRATION_GITLAB_BDD_CUCUMBER_TESTS_ARTIFACT_NAME | N/A | Name of the GitLab artifact that contains BDD Cucumber test result file paths to be extracted and processed.
CI_INTEGRATION_GITLAB_JUNIT_TESTS_ARTIFACT_NAME | N/A | Name of the GitLab artifact that contains JUnit test result file paths to be extracted and processed.
CI_INTEGRATION_GITLAB_USE_PARAMETERS | false | Decide on whether to use inputs or variables.
CI_INTEGRATION_GITLAB_VARIABLE_SOURCES | GROUP, PROJECT | Where variables can be sourced from: GROUP, PROJECT, INSTANCE, or NONE.
ENABLE_CI_INTEGRATION_FOR_GITLAB | false | Enables or disables GitLab integration. Enable the parameter on the space in which the CI server is defined.
GITLAB_CONNECTION_TIMEOUT_IN_SECONDS | 10 | Defines a timeout (in seconds) for connection to GitLab servers.
GITLAB_READ_REQUEST_TIMEOUT_IN_SECONDS | 30 | Defines a timeout (in seconds) for any read request to GitLab.

For details, see Configuration parameters.

## Prepare GitLab access tokens

To allow interaction with GitLab, you need an access token. The token must be able to read repository data and variables as needed for your integration scenario. You can create one of the following token types: Personal access token, Project-level token, Group/instance-level token.

### Token requirements:

Functionality | Minimum required role | Minimum scope
--- | --- | ---
Display pipeline results and test results injection | Guest | `read_api`
Run pipeline with no parameters | Developer | `api`
Run pipeline with inputs | Developer | `api`
Run pipeline with variables | Maintainer | `api`
Test runner | Maintainer | `api`

You still need at least Maintainer role to create the webhook manually in the GitLab project.

For details, refer to the GitLab documentation.

## Set up credentials

Add the GitLab token as credentials in OpenText Software Delivery Management.

To add credentials:

1. Open the global menu and select Administration > General Settings.

2. Select a shared space or workspace.

3. Select the Credentials tab.

4. Click the + Credentials button.

5. Paste the GitLab token into the password field.
6. In the Name and User Name fields, assign descriptive values that help identify the credential, such as the associated GitLab user or purpose.

## Add a GitLab CI server

CI servers are defined at the workspace level.

To add a GitLab CI server:

1. Select a workspace.
2. Select the DevOps > CI Servers tab.
3. Click the + CI Server button.
4. Enter a name for the CI server and select GitLab as the CI Server Type.
5. Enter the base URL for your GitLab instance. Example: `http://example.gitlab.com`.
6. After the CI server is created successfully, add the Credential field to the CI server grid and assign the previously created credential.

## Create API access tokens

Create API access tokens to use in the GitLab wekhooks.

To create API access tokens:

1. Select the shared space .
2. Select the API Access tab.
3. Click the + API access button.
4. Select Token as the type.
5. Assign the CI/CD Integration role for the relevant workspace.
6. Copy the generated token and store it securely. It is displayed only once. If lost, the token needs to be regenerated.

## Configure GitLab webhooks

Webhooks can be defined at the project or group level (depending on your GitLab license). Go to your GitLab project or group, and add a webhook with the settings below.

Setting | Definition
--- | ---
URL | `{{SDM_url}}/api/shared_spaces/{{space_id}}/analytics/ci/gitlab_ci/webhook-events` SDM_url: The base URL of OpenText Software Delivery Management. space_id: The ID of the shared space where the CI Server was added.
Custom headers | Add the following custom headers: `ALM-OCTANE-TECH-PREVIEW: true` `Authorization: Bearer {{SDM_token}}` SDM_token is the API access token generated by OpenText Software Delivery Management.
Triggers | Define the following triggers: Job Events Pipeline Events

Troubleshooting: After upgrading to a new OpenText Software Delivery Management version, if a 401 HTTP error code is returned when testing the webhook connection, first verify the configuration. If the configuration is correct, ensure that the hpssoconfig.xml file has also been updated to the latest version, as outlined in the upgrade guide. For details, see Upgrade procedure.

## Work with pipelines

Use the following procedures to work with GitLab pipelines in OpenText Software Delivery Management.

### Add a GitLab pipeline

1. Open the global menu and select Quality Management > Pipelines > Management.
2. Click the + Pipeline button.
3. Select the GitLab CI server you configured, then choose the relevant job from your GitLab project.

A multi-branch pipeline is created in OpenText Software Delivery Management, which serves as a reference to the corresponding GitLab project.

### Manage multi-branch pipelines

Multi-branch pipelines automatically track runs from any branch in your GitLab project. Users can configure branch filters to control which branches are monitored and injected into OpenText Software Delivery Management.

Note: The pipeline must be executed at least once in GitLab for it to appear in OpenText Software Delivery Management.

### View pipeline runs and test results

Pipeline runs are displayed in OpenText Software Delivery Management from GitLab. Note the following:

- Configure your YAML file to archive XML test result files at the end of each test job.
- The test results injection process is controlled by CI_INTEGRATION_GITLAB_BDD_CUCUMBER_TESTS_ARTIFACT_NAME and CI_INTEGRATION_GITLAB_JUNIT_TESTS_ARTIFACT_NAME.
- After the job completes, the results are analyzed and displayed in the pipeline run.

The values of CI_INTEGRATION_GITLAB_BDD_CUCUMBER_TESTS_ARTIFACT_NAME and CI_INTEGRATION_GITLAB_JUNIT_TESTS_ARTIFACT_NAME must be different. These parameters are mandatory for test results injection. For UFT One testing, CI_INTEGRATION_GITLAB_JUNIT_TESTS_ARTIFACT_NAME is reused.

The artifact file that contains test result paths must use the following JSON structure:

JSON file structure:

    {
        "job_id": 12345,
        "artifacts_base_path": "my-path/test-artifacts",
        "files": [
            { "path": "my-path/test-artifacts/test1.xml" },
            { "path": "my-path/test-artifacts/test2.xml" }
        ]
    }

- `job_id`: The job ID that generated the test result artifacts.
- `artifacts_base_path`: The common folder path to the test results.
- `files`: The array that contains test result file paths.
- `path`: The full path to a test result file, including the file name.

Test results injection may fail if files to download are empty or have an invalid format. Supported formats are JSON (for path/input files) and XML (for test result files). Any other format is rejected.

## Track GitLab pipeline run variants as separate pipeline views

When multiple pipeline run variants (for example, quick, full, nightly) are defined in the same GitLab pipeline configuration, grouping all runs in one pipeline view can make analysis less focused. Use the ALM_OCTANE_CI_PIPELINE_IDENTIFIER CI variable to create a child pipeline view with an additional identifier value in the pipeline path, so each variant can be tracked independently.

ALM_OCTANE_CI_PIPELINE_IDENTIFIER must be set as a CI variable - either in the pipeline configuration or passed at trigger time. GitLab inputs, which parameterize the pipeline configuration before a run is created, cannot be used for this purpose.

To create separate pipeline views for GitLab pipeline variants:

1. In GitLab, set ALM_OCTANE_CI_PIPELINE_IDENTIFIER as a CI variable in the pipeline configuration or pass it at trigger time.

2. Assign a distinct value for each pipeline variant that you want to track separately.

3. Trigger a pipeline run in GitLab using the selected variable value.

4. If the parent pipeline uses branch filters, ensure that the resulting child pipeline path matches those filters so the child pipeline view is created.

5. In OpenText Software Delivery Management, open Pipelines and locate the child pipeline view with the additional identifier value in its pipeline path.

These identifier-based child pipeline views are available for analysis in OpenText Software Delivery Management but cannot be triggered from OpenText Software Delivery Management.

## Run pipelines

You can run single-branch pipelines directly from OpenText Software Delivery Management. Multi-branch pipelines can only be run from GitLab.

Set the CI_INTEGRATION_GITLAB_USE_PARAMETERS accordingly to support pipelines with parameters or variables. It is recommended to use input parameters rather than variables.

Pipeline configuration | Run details
--- | ---
Pipelines without parameters or variables | Run directly from OpenText Software Delivery Management without any additional configuration.
Pipelines with parameters | Parameters are securely fetched from a JSON file located in the root of the GitLab repository. The file name must match the value configured in the CI_INTEGRATION_GITLAB_INPUTS_ARTIFACT_NAME parameter. JSON file structure:
    [
    	{
    	"{{param_name}}": {{param_value}}
    	}
    ]
Where `param_name` is the name defined in the YAML file.
Pipelines with variables | The variables defined in GitLab are used. To fetch current parameter values from GitLab, select Sync with CI.

## Run tests

Test runners in OpenText Software Delivery Management enable users to execute automated tests through dedicated GitLab pipelines.

The corresponding pipeline for the test runner needs to be added to OpenText Software Delivery Management prior to running automated tests.

Configure the following variable at the instance, group, or project level in GitLab: `testsToRun`.

Example (Maven): `mvn clean test -DTest=$testsToRun`

When creating a test runner in OpenText Software Delivery Management, select the appropriate testing framework (for example, JUnit, UFT, or Cucumber). The `testsToRun` parameter is generated automatically based on the selection.

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: