GitLab CI template for Spectral¶

This project implements a GitLab CI/CD template to lint JSON/YAML documents with Spectral with custom ruleset, and out of the box support for OpenAPI and AsyncAPI.

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/spectral/gitlab-ci-spectral@1.1.2
    # 2: set/override component inputs
    inputs:
      extra-args: "--ruleset custom.spectral.yaml" # ⚠ this is only an example

Use as a CI/CD template (legacy)¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/spectral'
    ref: '1.1.2'
    file: '/templates/gitlab-ci-spectral.yml'

variables:
  # 2: set/override template variables
  SPECTRAL_EXTRA_ARGS: "--ruleset custom.spectral.yaml" # ⚠ this is only an example

Global configuration¶

The Spectral template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
`image` / `SPECTRAL_IMAGE`	The Docker image used to run `spectral`	`registry.hub.docker.com/stoplight/spectral:latest`

Jobs¶

`spectral` job¶

This job performs a lint analysis of your API document(s) (OpenAPI, AsyncAPI...), mapped to the build stage.

It uses the following variable:

Input / Variable	Description	Default value
`documents` / `SPECTRAL_DOCUMENTS`	Location of JSON/YAML documents to be linted. Can be either a file, a glob or fetchable resource(s) on the web	`{,api/,src/main/resources/}{openapi,oas,swagger,asyncapi}.{json,yml,yaml}` see glob syntax for more details
`extra-args` / `SPECTRAL_EXTRA_ARGS`	Extra arguments for the Spectral CLI	none
`disabled` / `SPECTRAL_DISABLED`	Set to `true` to disable this job	none

`$SPECTRAL_DOCUMENTS` default value¶

The default value is configured to lookup documents as below:

# Folder locations 
- ${project_root}
- ${project_root}/api
- ${project_root}/src/main/resources

# Filenames containing below keywords
- openapi
- oas
- swagger
- asyncapi

# File extentions
- json
- yaml
- yml

Ruleset File¶

If you don't specify an explicit ruleset file with the --ruleset option, the Spectral CLI looks for a ruleset file called .spectral.yml, .spectral.yaml, .spectral.json or .spectral.js in the current working directory.

If none is present in your project, the template creates a default .spectral.yaml file with below content:

extends: spectral:oas           # out-of-the-box OpenAPI ruleset provided by Spectral

`$SPECTRAL_EXTRA_ARGS` use cases¶

The $SPECTRAL_EXTRA_ARGS can be used to override the defaults for optional arguments. Below are the most probable use cases:

Custom Ruleset location

Spectral uses the .spectral.yaml file in the root folder as convention for the ruleset.

If there is a need to specify any other location (remote URL or other filename), the $SPECTRAL_EXTRA_ARGS variable shall be overridden.

Fail-Severity

Spectral default to error fail-severity.