# 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](https://docs.xygeni.io/xygeni-administration/profile#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@ inputs: stage: test # any additional input follows # Create a job that extends the template xygeni-scanner: extends: .xygeni-scanner-job ``` Where `` 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-`, where `` 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: {% 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**
**Benefits of Integration:** * Centralized security reporting in GitLab * Automated vulnerability tracking * Historical trend analysis * Integration with GitLab's issue tracking system * Compliance reporting capabilities ``` ```