GitLab Workflow

Prerequisites

Add XEIZE_TOKEN and a GitLab API token as CI/CD variables. The GitLab API token can be named XEIZE_GITLAB_API_TOKEN or GITLAB_API_TOKEN.

XEIZE Token

Obtain an XEIZE_TOKEN to use XEIZE with GitLab Workflow.

GitLab PAT Token

To post comments, provide a GitLab personal access token through XEIZE_GITLAB_API_TOKEN or GITLAB_API_TOKEN with the following scope. When both variables are set, XEIZE_GITLAB_API_TOKEN takes precedence; GITLAB_API_TOKEN is used only when that value is empty.

The token's user must also have project membership permissions to view the code and comment on merge requests. read_api is read-only and insufficient; write_repository does not authorize REST API access. See GitLab's access token scopes and project permissions.

For token creation, see the GitLab PAT guide.

The XEIZE job fails regardless of LEVEL if both GitLab token variables are missing, or the selected token is expired, rejected, or lacks the required permissions. Where possible, the selected token posts one authentication-error comment on the merge request. No comment is attempted when both variables are missing. If the selected token itself is rejected, it cannot authenticate a comment either. Use the GitLab job log as the reference; the other token variable is not retried.

The job log highlights the authentication error once in a box. Reason explains the cause, MR comment indicates whether a comment was posted, and Action explains how to resolve it. To block merging, require a successful pipeline in the project's merge settings.

CI_JOB_TOKEN is not used as an alternative credential. GitLab's job token permissions do not allow comment creation through the Merge Request Notes API.

A GitLab API 5xx, rate-limit, or network error alone does not establish that a token is invalid and does not block the pipeline or merge request. If a comment-creation POST returns 5xx, it is retried once after 500 ms. A second failure produces a XEIZE REPORTING DEGRADED - CI NOT BLOCKED box in the job log and, where possible, one top-level MR warning note. Failure to post that additional note does not change the result.

403 insufficient_scope is a permission error for the selected token and fails the pipeline. If findings also meet the LEVEL threshold, the vulnerability gate remains in effect despite the reporting failure. GitLab inline discussions use the SHAs from the MR diff version matching the scanned source SHA. If no version matches, XEIZE asks you to rerun the latest MR pipeline instead of sending an invalid position.

Scan result language

Add LANG to variables to choose the language of SAST, Secret, and IaC findings and comments on the merge request.

yaml

variables:
  LANG: "JP"

Supported values are KO (Korean), EN (English), and JP (Japanese). Korean is the default when LANG is unset.

Examples

SAST

yaml

image: alpine:3.24
stages:
  - sast
before_script:
  - apk update && apk add --no-cache git curl
variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 0
  LANG: "JP"
sast:
  stage: sast
  script: |
    curl -L -o xez_ci "https://download.xeize.dev/ci/ci_linux_x64" -H "X-XEZ-TOKEN: $XEIZE_TOKEN"
    chmod +x xez_ci
    GIT_PLATFORM=gitlab ./xez_ci

Secret

yaml

image: alpine:3.24
stages:
  - secret
before_script:
  - apk update && apk add --no-cache git curl
variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 0
  MODE: secret
  LANG: "JP"
secret:
  stage: secret
  script: |
    curl -L -o xez_ci "https://download.xeize.dev/ci/ci_linux_x64" -H "X-XEZ-TOKEN: $XEIZE_TOKEN"
    chmod +x xez_ci
    GIT_PLATFORM=gitlab ./xez_ci

IaC

yaml

image: alpine:3.24
stages:
  - iac
before_script:
  - apk update && apk add --no-cache git curl
variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 0
  MODE: iac
  LANG: "JP"
iac:
  stage: iac
  script: |
    curl -L -o xez_ci "https://download.xeize.dev/ci/ci_linux_x64" -H "X-XEZ-TOKEN: $XEIZE_TOKEN"
    chmod +x xez_ci
    GIT_PLATFORM=gitlab ./xez_ci

Blocking merges with LEVEL

yaml

image: alpine:3.24
stages:
  - sast
before_script:
  - apk update && apk add --no-cache git curl
variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 0
sast:
  stage: sast
  script: |
    curl -L -o xez_ci "https://download.xeize.dev/ci/ci_linux_x64" -H "X-XEZ-TOKEN: $XEIZE_TOKEN"
    chmod +x xez_ci
    GIT_PLATFORM=gitlab LEVEL=high ./xez_ci

Filtering findings with AUDIT LEVEL

yaml

image: alpine:3.24
stages:
  - iac
before_script:
  - apk update && apk add --no-cache git curl
variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 0
iac:
  stage: iac
  script: |
    curl -L -o xez_ci "https://download.xeize.dev/ci/ci_linux_x64" -H "X-XEZ-TOKEN: $XEIZE_TOKEN"
    chmod +x xez_ci
    GIT_PLATFORM=gitlab MODE=iac LEVEL=high AUDIT_LEVEL=low ./xez_ci

Push pipeline without an MR

This runs SAST, Secret, and IaC with MODE=all when code is pushed to develop, then builds and deploys after a successful scan. Add XEIZE_TOKEN as a CI/CD variable.

yaml

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "develop"'

stages: [security, build, deploy]

security:
  stage: security
  image: alpine:3.24
  allow_failure: false
  variables:
    GIT_DEPTH: "0"
    MODE: all
    LEVEL: medium
  before_script:
    - apk add --no-cache git curl
  script: |
    curl -fsSL -H "X-XEZ-TOKEN: $XEIZE_TOKEN" https://download.xeize.dev/ci/ci_linux_x64 -o /tmp/xez_ci
    chmod +x /tmp/xez_ci
    GIT_PLATFORM=gitlab /tmp/xez_ci

build:
  stage: build
  needs: [security]
  script:
    - ./ci/build.sh

deploy:
  stage: deploy
  needs: [build]
  script:
    - ./ci/deploy.sh

Replace build/deployment commands and runner settings for your project while preserving the security → build → deploy dependencies. See common settings for scan scope and error handling.

Prerequisites

XEIZE Token

GitLab PAT Token

Scan result language

Examples

SAST

Secret

IaC

Blocking merges with LEVEL

Filtering findings with AUDIT LEVEL

Push pipeline without an MR

Related pages1

Detailed guide