Gitlab Pipeline

You can run Code Security scans on a Gitlab pipeline to secure merge requests. To secure your merge requests without using pipelines, use the Code Security Gitlab Bot.

Basic Configuration

In the SPECTRAL_DSN file, set Integration Environment Variables to define the scan.
In your Gitlab environment, upload the SPECTRAL_DSN file to the Gitlab CI/CD Variables.

Best Practice - Verify the digest of a downloaded runnable file before you run it. You can use Code Security Preflight to verify the digest. Follow this link to see SHA digests of the binary, the download script and the gzip.

Code Security Integration Environment Variables for Gitlab Pipeline

Name	Required	Description
`GITLAB_TOKEN`	Yes	Generate it in your Gitlab profile -> Access Tokens, check the "api" scope (leave blank if you are using vault)
`SELF_HOSTED_GITLAB_DOMAIN`	Yes	If you are running a self-hosted Gitlab, enter the domain. For example: https://my-gitlab-domain.com
`SPECTRAL_DSN`	Yes	Your Spectral DSN retrieved from SpectralOps (leave blank if you are using vault)
`SPECTRAL_TAGS`	No	Tags list to run Spectral with, separated by commas (for example: base,iac,audit)
`SPECTRAL_ENGINES`	No	Engines list to run Spectral with, separated by commas (for example: secrets,iac,oss). Default is 'secrets'
`STRICT_MODE`	No	If set to true, check status is based on all issues found in the modified files (even if the issues are old)

Example of a Basic Configuration:

Copy

build-job:
  stage: build
  script:
    - curl -L "https://app.spectralops.io/latest/x/sh?dsn=$SPECTRAL_DSN" | sh
    # This takes your SPECTRAL_DSN from the variables store in Gitlab CI/CD
    - $HOME/.spectral/spectral scan --ok  --include-tags base,audit

Advanced Configuration: Gitlab Pipeline Scan of Changed Files

In an advanced configuration, you can limit the scan of the Gitlab Pipline on changed files. This feature is supported only on Standalone GitLab servers.

Prerequisites

Only Standalone GitLab servers are supported
You must use Docker Docker (specifically, Docker Engine) is a software technology providing operating-system-level virtualization also known as containers. in your Gitlab environment to limit the scan to changed files.

You can limit the scan to after a Merge Request event or to after a Standalone Push.

Setting

Description

Merge Request Events

When the job runs in a merge request context, Code Security scans only the files that were changed in this merge request.

Best Practice - Change the repository configuration to allow merges only f the pipeline is successful.

Standalone Pushes

If the job runs without a merge request context, Code Security finds the diff (changed files) between these commits:

the last commit
the last commit before the push

Then, Code Security scans only the diff between these commits.

To limit a scan of a Gitlab Pipeline to changed files:

In your Gitlab pipeline, define a job in the .gitlab-ci.yml configuration file to run a dedicated docker image named checkpoint/spectral-gitlab-pipeline-scanner

Example of a configuration in the gitlab-ci.yml file that limits the scan to after Merge Request Events

Copy

spectral-scan:
  stage: test # specify which stage the job should run
  allow_failure: true # should the job fail the whole pipline
  image: checkpoint/spectral-gitlab-pipeline-scanner:latest
  script:
    - /usr/src/app/scanner
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

Example of a configuration in the gitlab-ci.yml file that limits the scan to a direct push to the main branch (Standalone Push)

Copy

spectral-scan:
  stage: test # specify which stage the job should run
  allow_failure: true # should the job fail the whole pipline
  image: checkpoint/spectral-gitlab-pipeline-scanner:latest
  script:
    - /usr/src/app/scanner
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH