Skip to main content

GitLab Integration

GitLab is a web-based DevOps life cycle tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration/continuous deployment pipeline features. GitLab offers the ability to automate the entire DevOps life cycle from planning to creation, build, verify, security testing, deploying, and monitoring offering high availability and replication, and scalability and available for using on-prem or cloud storage.


Checkmarx integrates with GitLab, enabling the identification of new security vulnerabilities with proximity to their creation. GitLab integration triggers Checkmarx scans as defined by the GitLab CI/CD pipeline. Once a scan is completed, both scan summary information and a link to the Checkmarx Scan Results will be provided. Both CxSAST and CxSCA are supported within the GitLab integration.

CxFlow Overview

CxFlow is a Spring Boot application written by Checkmarx that enables initiations of scans and result orchestration. It is the main automation driving the GitLab and Checkmarx integration. Some features of CxFlow include:

  • Automated project creation

  • Facilitates feedback channels in a closed loop nature

    • Channels include GitLab Issues, GitLab Merge Requests, JIRA, Rally, and ServiceNow.

  • Enables customers to incorporate Checkmarx into their DevOps/Release pipelines as early as possible

  • Controls the “breaking” of builds

CxFlow is an open source project written and maintained by Checkmarx. For access to CxFlow’s Wiki, please refer to CxFlow Wiki.

GitLab Integration Flow

There are several ways of integrating Checkmarx security scans into GitLab’s ecosystem. This document specifically outlines how to integrate GitLab with Checkmarx’s Containerized CxFlow CLI. For more info on integrating with GitLab’s Webhook feature, please refer to CxFlow Webhook Workflows.

The following steps represent the containerized CxFlow CLI integration flow:

  1. GitLab’s CI/CD pipeline is triggered (as defined in the .gitlab-ci.yml file)

  2. During the test stage of GitLab’s CI/CD pipeline, Checkmarx’s containerized CxFlow CLI is invoked

  3. CxFlow CLI triggers a security scan via the Checkmarx Scan Manager

  4. Results can be configured to be displayed with GitLab’s ecosystem or a supported bug tracker via CxFlow YAML configuration

    1. Results will be within Checkmarx Scan Results within the Checkmarx Manager Server

    2. Results can be accessed within GitLab’s Merge Request Overview (if the scan was initiated during a Merge Request)

    3. Results can be accessed within GitLab’s Issues if configured (or can be filtered into external bug tracker tools)

    4. Results can be accessed within GitLab’s security dashboard, if you have access to it (Gold/Ultimate packages or if your project is public)


Within GitLab, CxFlow CLI will zip the source directory of the repository and send it to the Checkmarx Scan Manager to perform the security scan.


  • GitLab can access a running Checkmarx CxSAST Server with an up-to-date Checkmarx license

  • If performing CxSCA scans, you must have a valid CxSCA license and GitLab must be able to access the CxSCA tenant

  • To review scan results within GitLab’s Security Dashboard, you need the Gold/Ultimate tier or the GitLab project must be public

    • To review results in the issue management of your choice (i.e., JIRA) extra configuration is needed, please refer to CxFlow Bug Trackers

CI/CD Variables

To allow for easy configuration, it is necessary to create environment variables with GitLab to run the integration. For more information on GitLab CI/CD variables, visit here: GitLab: CI/CD - Environment Variables

Edit the CI/CD variables under Settings → CI / CD → Variables and add the following variables for a CxSAST and/or CxSCA scan :




API token to create Merge Request Overview entries, should have “api” privileges.

To create a personal token, click your Gitlab profile in the upper right corner >settings

  • Click Access Tokens and add a personal access token.

  • Give the token api, read_user, write_repository, read_registry scopes.

For additional information on creating a Personal Access Token, refer to GitLab: Personal Access Tokens


Type of bug tracking ('GitLabDashboard' or ‘GitLab’). For vulnerabilities to be exported to GitLab’s Dashboard, use ‘GitLabDashboard’ and for vulnerabilities to be added to GitLab’s Issues, use ‘GitLab’. For more details on complete list of Bug Trackers, please refer to CxFlow Configuration


Password for CxSAST


The URL of CxSAST Manager Server (i.e.,


This variable is applicable only when integrating GitLab with CxSAST. When configuring an integration with cloud CxSCA, set these variables as appropriate for your region: SCA_ACCESS_CONTROL_URL; SCA_API_URL; SCA_APP_URL.


User Name for the CxSAST Manager. User must have ‘SAST Scanner’ privileges. For more information on CxSAST roles, please refer to CxSAST / CxOSA Roles and Permissions


Checkmarx Team Name (i.e., /CxServer/teamname)


The name of the CxSCA Team (i.e., /CxServer/teamname)


The name of the CxSCA Account (i.e., SCA-CompanyName). Only needed if you have a valid license for CxSCA.


The username of the CxSCA Account. Only needed if you have a valid license for CxSCA.


The password of the CxSCA Account. Only needed if you have a valid license for CxSCA.


The URL of the CxSCA access control appropriate for your region.


The URL of the CxSCA API appropriate for your region.


The URL of the CxSCA application appropriate for your region.

Pipeline Configuration

The GitLab CI/CD pipeline is controlled by a file named ‘.gitlab-ci.yml’ located in the root directory of the project. Please refer to GitLab: CI YAML for more info.


If you are using TLS certificates, please review the Advanced Options section


Checkmarx provides a template that you can use that already has jobs defined for the pipeline. All you need to do is add this one line that includes the template file.

include: ''

If you need to override any parameters or variables of the scan, all you need to do is define the variables in the .gitlab-ci.yml file. For example, let’s say you want to use a different preset and also enable CxSCA scans with filtering on High. Your .gitlab-ci.yml file would look like this:

include: ''

    SCA_TEAM: "/CxServer/team"

Scanning Existing Projects

If you are scanning an already existing project, you will need to override the existing variables such as folders being excluded. You can do this by overriding the variable CHECKMARX_SETTINGS_OVERRIDE.

include: ''



With GitLab, the order of precedence when it comes to variables is:

  1. Environment variables

  2. Variables defined in .gitlab-ci.yml file

  3. Variables defined in Checkmarx template file

Run Pipeline

To run a Checkmarx scan, you need to trigger the pipeline. The trigger is based on the .gitlab-ci.yml and in the provided sample above, it will be triggered on Merge Requests and on changes to the master branch.

Review Results

While the scan results will always be available in the Checkmarx UI, users can also access results within the GitLab ecosystem. Currently there are three different ways to review results from the scan:

  • Merge Request Overview

  • GitLab Issues

  • Security Dashboard

Merge Request Discussion

When you have configured the .gitlab-ci.yml file to scan on merge_requests issues (please refer to GitLab: Pipelines for Merge Requests), a high level report of the Checkmarx scan will be displayed within GitLab Merge Request Overview.

An example of a Merge Request with a Checkmarx scan report can be found in the below image.


GitLab Issues

When you have configured the BUG_TRACKER variable to use “GitLab”, CxSAST and CxSCA issues found in Checkmarx will be opened within GitLab Issues. For more information on GitLab issues, please refer to GitLab: Issues

An example of Issues created can be found in the below image.


Security Dashboard

With the Gold/Ultimate tier for GitLab, or if the project is public, you can review results in GitLab’s Security Dashboard. For information on GitLab’s Security Dashboard, please refer to GitLab: Security Dashboard

An example of vulnerabilities displayed in the Security Dashboard can be found in the below image.


Advanced Options

On Premise GitLab

For On Premise GitLab Instances, you need to override the GITLAB_URL command in your .gitlab-ci.yml file. By default, it points to the cloud version of GitLab so you need to input the location of your GitLab instance. Below is an example, replace ‘’ with the location of your on premise GitLab instance.


Proxy Support

For Proxy support, you need to override the CX_FLOW_EXE command in your .gitlab-ci.yml file. Enter the appropriate host, port, user, and password as show here:

    CX_FLOW_EXE: "java -Dhttp.proxyPort=9595 -Dhttp.proxyUser=<proxy user> -Dhttp.proxyPassword=<proxy password> -jar /app/cx-flow.jar"

For detailed info, please refer to CxFlow Proxy & HTTPS Configuration.

Adding Certs

If you are using TLS, you will need to add additional options or you will see an error.


When executing the CxFlow container commands from the following error is displayed:

ERROR 11 --- [ main] com.checkmarx.flow.CxFlowRunner : An error occurred while processing request

148 org.springframework.web.client.ResourceAccessException: I/O error on POST request for "": PKIX path building failed: unable to find valid certification path to requested target; nested exception is PKIX path building failed: unable to find valid certification path to requested target


The TLS certificate of the Checkmarx server is not trusted by the CxFlow client. This may be because the Checkmarx server’s TLS certificate is self-signed. Another possibility is that the Checkmarx server’s TLS Certificate was signed by a certificate authority (CA) internal to the company.


You have to put the correct certificate into the container’s trusted certificate store:

  1. Obtain the correct certificate. If the Checkmarx server’s TLS certificate is self-signed, then you need the Checkmarx server’s TLS certificate. If the TLS certificate was signed by a company-internal CA, then you need the certificate of the internal CA. Get it in PEM Format, it’ll have a format of:

    ------- BEGIN CERTIFICATE -------
    ------- END CERTIFICATE --------
  2. Create a variable of type FILE inside GitLab. Name it LOCAL_CA_CERT. Paste the contents of the certificate PEM file there.

  3. In your .gitlab-ci.yml add the following job


Edit checkmarx-scan depending on the trigger

      - cat ${LOCAL_CA_CERT} > localcert.cert
      - keytool -import -trustcacerts -alias localca -file localcert.cert -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -noprompt