Basic

Run a scan on the whole repository

Here's an example of a basic GitLab CI configuration that uses Spectral:

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

It's recommended to verify the digest of a downloaded runnable file before you run it. You can use Spectral's Preflight to verify. Follow this link to see SHA digests of the binary, the download script and the gzip.

Environment Variables

Store your SPECTRAL_DSN in Gitlab CI/CD Variables.

Set the engines and tags you want to include in your scan (or any other flag / arg) directly in the YML.

Advanced

Run a scan focusing on changed files (Docker based)

Gitlab pipeline scanner brings optimal developer experience by focusing on the actual problems in your change set.

There are two running run modes possible for the job:

1. On a Merge Request event - when the job runs in a merge request context, the files that have been changed in this merge request are being scanned (it is highly recommended changing the repository configuration so that merges can only be done if the pipeline is successful).
2. After a standalone Push - If the job runs without a merge request context, it calculates the diff (changed files) between the last commit, and the last commit before the push, and runs the scan on those files.

The integration is done by a job (defined in gitlab-ci.yml), running a dedicated docker image called checkpoint/spectral-gitlab-pipeline-scanner.
You can also define the trigger for this job by using the rules property as shown in the examples below.

NOTE: This is a docker based job, therefore it should run in a GitLab runner using docker executor.

Environment Variables

Store the next variables in Gitlab CI/CD Variables:

Examples

Here are some examples of configuration the job in .gitlab-ci.yml file

Running after merge requests events:

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'

Running after a direct push to the main branch:

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

Support

NOTE: The advanced integration is currently supported only on Standalone GitLab servers.

Additional GitLab integrations

In case you wish to secure your merge requests without using pipelines, you can use Spectral GitLab webhook scanner.