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 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) configuration is needed in the CxFlow YAML file, 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 :

The key CX_FLOW_CONFIG variable must be of type "File"




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.

  • Copy this token and keep safe - it should be pasted into the token: <> of the application.yml

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


(Type: Variable)

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


(Type: Variable)

Password for CxSAST


(Type: Variable)

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


(Type: Variable)

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 (v9.0.0 and up)


(Type: File)

enable-vulnerability-scanners: - sca and the sca block are only needed if you have a valid CxSCA license and tenant.

    name: cx-flow.log

  bug-tracker:  ${BUG_TRACKER}
    - GitLab
    - GitLabDashboard
    - High
  break-build: true
    - sast
    - sca

  version: 9.0
  client-secret: 014DF517-39D1-4453-B7B3-9930C563627C
  base-url: ${CHECKMARX_SERVER}
  url: ${CHECKMARX_SERVER}/cxrestapi
  portal-url: ${CHECKMARX_SERVER}/cxwebinterface/Portal/CxWebService.asmx
  multi-tenant: true
  incremental: true
  scan-preset: Checkmarx Default
  configuration: Default Configuration
  scan-timeout: 120


  false-positive-label: false-positive
  file-path: ./gl-sast-report.json


(Type: Variable)

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


(Type: Variable)

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


(Type: Variable)

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


(Type: Variable)

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

The above CX_FLOW_CONFIG File Variable is just an example and can be configured in many ways. Please refer to CxFlow Configuration for documentation on options to configure CxFlow.

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.

It is suggested not to over-pollute your companies already existing '.gitlab-ci.yml' file.  Instead, create a new YAML file in the root directory named ‘.checkmarx.yml’ and include it in ‘.gitlab-ci.yml’.


Note that image is a docker container maintained by Checkmarx.

Note that image is a docker container maintained by Checkmarx.


image: docker:latest
  - docker:dind

  stage: test
    entrypoint: ['']
    - cat ${CX_FLOW_CONFIG} > application.yml
    - |
      if [ "$CI_PIPELINE_SOURCE" == "merge_request_event" ]; then 
        java -jar /app/cx-flow.jar --spring.config.location=./application.yml \
          --scan \
          --cx-team="${CHECKMARX_TEAM}" \
          --cx-project="${CI_PROJECT_NAME}-${CI_COMMIT_REF_NAME}" \
          --app="${CI_PROJECT_NAME}" \
          --project-id=${CI_PROJECT_ID} \
          --merge-id=${CI_MERGE_REQUEST_IID} \
          --bug-tracker=GITLABMERGE \
          --cx-flow.break-build=false \
        java -jar /app/cx-flow.jar --spring.config.location=./application.yml \
          --scan \
          --cx-team="${CHECKMARX_TEAM}" \
          --cx-project="${CI_PROJECT_NAME}-${CI_COMMIT_REF_NAME}" \
          --app="${CI_PROJECT_NAME}-${CI_COMMIT_REF_NAME}" \
          --branch="${CI_COMMIT_REF_NAME}" \
          --repo-name="${CI_PROJECT_NAME}" \
          --namespace="${CI_PROJECT_NAMESPACE##*/}" \
          --cx-flow.break-build=false \
    when: on_success
      sast: gl-sast-report.json
      - gl-sast-report.json


include: '.checkmarx.yml'

  - test

  stage: test
    - master
    - merge_requests
  extends: .checkmarx_sast

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.

Have a question?  Want to report an issue?  Contact Checkmarx support