# GitLab Runner Integration

`GitLab` is an open-core company that provides GitLab, a DevOps software package that combines the ability to develop, secure, and operate software in a single application. Its application, [`GitLab Runner`](https://docs.gitlab.com/runner/), works with GitLab CI/CD to run jobs in a pipeline.

{% hint style="info" %}
The following configuration examples show how to install & run the scanner using an API Token stored as a secret named `XYGENI_TOKEN`. See [Generate Xygeni API Token for Scanner](/xygeni-administration/platform-administration/profile.md#generate_token_for_scanner-1) or ask your Xygeni administrator to generate it.

See [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/) and [using external secrets in CI](https://docs.gitlab.com/ee/ci/secrets/) for details on how to register the Xygeni API token for use in GitLab CI.
{% endhint %}

### Using the CI/CD Component

{% hint style="warning" %}
The CI/CD Component may not be available with an Gitlab On-Premise solution.
{% endhint %}

Xygeni provides an officially supported **GitLab CI/CD Component** named **`xygeni-scanner`**, available in the GitLab Marketplace: [Gitlab Xygeni CI/CD Component](https://gitlab.com/explore/catalog/xygeni/gitlab-ci-integration)

This component runs multiple kinds of scans on the GitLab repository. The scanner is automatically updated and cached for performance. All you need is a Xygeni API token registered as a pipeline secret.

To add this component to your CI/CD pipeline, add the following to your project's `.gitlab-ci.yml`:

```
include:
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@<tag>
    inputs:
      stage: test
      # any additional input follows

# Create a job that extends the template
xygeni-scanner:
  extends: .xygeni-scanner-job
```

Where `<tag>` is the release tag you want to use ([releases list](https://gitlab.com/xygeni/gitlab-ci-integration/-/releases)). Use `~latest` for the latest published component.

{% hint style="warning" %}
Using `~latest` is not recommended: it is safer to always pin components to a specific release, to avoid supply chain attacks. In the following examples we use `~latest` so you can copy and paste the examples for testing. Set a specific release in production environments.
{% endhint %}

The component provides a hidden job template `.xygeni-scanner-job` that you extend with your own job name. This allows you to customize the job name and add additional configuration like `artifacts`, `allow_failure`, or other job-level settings.

#### Multiple Configurations

You can include the component multiple times with different configurations by using the `name` input parameter. Each unique `name` creates a separate template that won't collide:

```
include:
  # Secrets scan configuration
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@~latest
    inputs:
      name: secrets
      stage: test
      run: secrets
      to-xygeni: false
      fail-on: high

  # Full security scan configuration
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@~latest
    inputs:
      name: full
      stage: security
      run: sast,deps,suspectdeps,misconf
      to-vuln-report: true

# Create jobs extending each template
secrets-scan:
  extends: .xygeni-scanner-secrets

full-security-scan:
  extends: .xygeni-scanner-full
  artifacts:
    reports:
      sast: gl-xygeni-sast-sast.json
      dependency_scanning: gl-xygeni-suspectdeps-dependency_scanning.json
```

The job in template follows the pattern `.xygeni-scanner-<name>`, where `<name>` is the value of the `name` input (defaults to `job`). Extend the appropriate job as needed.

{% hint style="info" %}
For more examples of uses please go to the Gitlab page of the CI/CD component: <https://gitlab.com/explore/catalog/xygeni/gitlab-ci-integration>
{% endhint %}

### Without using the CI/CD Component

{% hint style="warning" %}
For Cloud Based Gitlab, the CI/CD component is the recommended option. Use this option only if the CI/CD Component is not available.
{% endhint %}

The CI/CD Component may not be available in some Gitlab On-Premise installations, in this case, the pipeline must be configured manually.

Move to the left panel, Build>Pipeline Editor and Create a new pipeline or modify the existing one. And add the following code and make sure the stage name marches the defined stages in the pipeline:

```
.xygeni-scan-definition:
  image: maven:3.9-eclipse-temurin-21

  before_script:
    - apt-get update && apt-get install -y unzip curl

  script:
    - curl -L https://get.xygeni.io/latest/scanner/install.sh | /bin/bash -s -- -t "${XYGENI_TOKEN}" -s https://api.xygeni.io
    - |
      $HOME/.xygeni/xygeni scan --never-fail -d $CI_PROJECT_DIR

xygeni_scan:
  stage: test
  extends: .xygeni-scan-definition
```

### Integrate with Gitlab Security Reports

GitLab provides built-in security reporting capabilities that allow you to view security vulnerabilities directly within your GitLab project. When integrated with Xygeni, security findings can be automatically sent to GitLab's security dashboard, providing a centralized view of your project's security posture.

#### Sending Xygeni Secrets Findings to GitLab

Xygeni can automatically send secrets detection findings to GitLab's security dashboard using the following command:

```linenums
include:
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@~latest
    inputs:
      stage: test
      to-vuln-report: true

xygeni-scanner:
  extends: .xygeni-scanner-job
  # Map the GitLab reports generated to the GL security scan category
  artifacts:
    reports:
      secret_detection: gl-xygeni-secrets-secret-detection.json
      sast: gl-xygeni-sast-sast.json

  allow_failure: true
```

{% hint style="info" %}
The `allow_failure: true` setting ensures that secrets findings don't block pipeline execution while still reporting them to GitLab's security dashboard for review and remediation.
{% endhint %}

**GitLab CI/CD Configuration:**

To properly receive Xygeni findings, ensure your GitLab project has the security scanning features enabled. The findings will appear in:

* **Security & Compliance > Vulnerability Report**
* **CI/CD > Pipelines > Security** tab for each pipeline run
* **Project > Security Dashboard**

<figure><img src="/files/UUunJFH3i9tQavODY7W4" alt="" width="251"><figcaption></figcaption></figure>

**Benefits of Integration:**

* Centralized security reporting in GitLab
* Automated vulnerability tracking
* Historical trend analysis
* Integration with GitLab's issue tracking system
* Compliance reporting capabilities

```
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xygeni.io/xygeni-administration/platform-administration/integrations/integrate-scanner-cli-into-ci-cd-systems/gitlab-runner-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.