gitlab-ci-verify

Validate and lint your gitlab ci files using ShellCheck, the Gitlab API, curated checks or even build your own checks

Features

• ShellCheck for scripts
• Validation against Pipeline Lint API for project
• Curated checks for common mistakes (feel free to contribute new ones)
• Automatic detection of the current gitlab project with an option to overwrite
• Available as pre-commit hook
• Usable to valid dynamically generated pipelines using the python wrapper
• Support for gitlab.com and self-hosted instances
• Support for custom policies written in Rego

Example output

Format	Screenshot
text
json
table

Installation

pre-commit

docker

Install with pipx

Using pipx you can just use the following command use gitlab-ci-verify as it is:

pipx install gitlab-ci-verify-bin

Install as library using pip

If you want to use it directly using the subprocess module you can install it with pip:

pip install gitlab-ci-verify

And use the package like this:

from gitlab_ci_verify import verify_file

# Verify .gitlab-ci.yml in /path/to/repo is valid
valid, findings = verify_file("/path/to/repo")

# verify include.yml in /path/to/repo is valid
valid, findings = verify_file("/path/to/repo", "include.yml")

# or if you want to verify file content for a given repository
# valid, findings = verify_content("/path/to/repo","ci-yaml content")

print(f"Valid:    {valid}")
print(f"Findings: {findings}")

Also see the python wrapper documentation

Manual

Linux (64-bit)

curl -LO https://github.com/timo-reymann/gitlab-ci-verify/releases/download/$(curl -Lso /dev/null -w %{url_effective} https://github.com/timo-reymann/gitlab-ci-verify/releases/latest | grep -o '[^/]*$')/gitlab-ci-verify_linux-amd64 && \
chmod +x gitlab-ci-verify_linux-amd64 && \
sudo mv gitlab-ci-verify_linux-amd64 /usr/local/bin/gitlab-ci-verify

Darwin (Intel)

curl -LO https://github.com/timo-reymann/gitlab-ci-verify/releases/download/$(curl -Lso /dev/null -w %{url_effective} https://github.com/timo-reymann/gitlab-ci-verify/releases/latest | grep -o '[^/]*$')/gitlab-ci-verify_darwin-amd64 && \
chmod +x gitlab-ci-verify_darwin-amd64 && \
sudo mv gitlab-ci-verify_darwin-amd64 /usr/local/bin/gitlab-ci-verify

Windows

Download the latest release for Windows and put in your PATH.

Install with go

go install github.com/timo-reymann/gitlab-ci-verify@latest

Supported platforms

The following platforms are supported (and have prebuilt binaries / ready to use integration):

• Linux
  • 64-bit
  • ARM 64-bit
• Darwin
  • 64-bit
  • ARM (M1/M2)
• Windows
  • 64-bit
• pre-commit (x86 & ARM)
• Docker (x86 & ARM)

Where to find the latest release for your platform

Binaries

Binaries for all of these can be found on the latest release page.

Docker

For the docker image, check the docker hub.

Usage

Command Line

gitlab-ci-verify --help

Containerized

docker run --rm -it -v $PWD:/workspace -e GITLAB_TOKEN="your token" timoreymann/gitlab-ci-verify

As pre-commit hook

- repo: https://github.com/timo-reymann/gitlab-ci-verify
  rev: v1.2.0
  hooks:
    - id: gitlab-ci-verify

Authentication with GitLab

The tool takes a few sources into consideration in the following order when authenticating with GitLab:

• --gitlab-token commandline flag
• netrc in your home folder
• Vault token specified via --gitlab-token vault://<path>#<field> with environment variable VAULT_ADDR set to base url for vault, and either VAULT_TOKEN set or ~/.vault-token present
• GITLAB_TOKEN environment variable

For the project detection, all git remote URLs of the repository are tried, and the first URL that returns a valid API response is used. In case you cloned via SSH it tries to convert it to the HTTPs host automatically. If the ssh URL differs from the HTTPs url you should specify it manually using the --gitlab-base-url, without protocol e.g. --gitlab-base-url git.example.com

Writing custom policies

You can write custom policies for your projects using Rego.

To get started to create the folder .gitlab-ci-verify/checks in your project and add a file with the extension .rego.

# package does not really matter, as long as is it does **not** contain gitlab_ci_verify
package my_project_checks

# Import helpers
import data.gitlab_ci_verify

# Use the latest and greatest v1 API
import rego.v1

# Define a rule that ensures each image has a tag
findings contains gitlab_ci_verify.error("PROJ-1001", sprintf("Job %s does not contain tag for image", [job]), yamlPathToLineNumber(sprintf(".%s.image", [job]))) if {
    some job in input.yaml[job]
    not contains(input.yaml[job].image, ":")
}

# Define a rule that nesures each pipeline has the job pages

findings contains finding if {
  not input.yaml.pages
  
  finding := gitlab_ci_verify.error("PROJ-1002", "The pipeline needs to contain a pages job", -1)
}

Provided helpers

Helpers are methods you can import and that are written in Rego to make it easier to write policies.

Signature	Description
gitlab_ci_verify.error(code, message, line)	Create a finding with the given code, message and line
gitlab_ci_verify.error_with_link(code, message, line, link)	Create a finding with the given code, message, line and link
gitlab_ci_verify.warning(code, message, line)	Create a warning with the given code, message and line
gitlab_ci_verify.warning_with_link(code, message, line, link)	Create a warning with the given code, message, line and link
gitlab_ci_verify.info(code, message, line)	Create an info with the given code, message and line
gitlab_ci_verify.info_with_link(code, message, line, link)	Create an info with the given code, message, line and link
gitlab_ci_verify.create_finding(level, code, message, line)	Create a finding with the given level, code, message and line

Extra builtins

The following additional builtins are available in the Rego policies:

Signature	Description
yamlPathToLineNumber(path)	Convert a YAML path to a line number, if nothing is found returns -1 which is accepted for findings, when they can’t be correlated to a line

Input

The input for the policies is based on the parsed gitlab ci file.

{
  "yaml": {
    // ... the parsed YAML from the disk
  },
  "mergedYaml": {
    // ... the merged YAML from the API, it is set to nil when run with the `--no-lint-api-in-ci` flag
  }
}

Remote bundles

You can use remote bundles to share policies between projects. To do so you can use the --include-opa-bundle flag to specify a bundle to include.

The bundle should be a tarball containing the rego files, built using opa.

To allow caching, the server should support RFC7232 compliant caching headers.

Further resources

• Rego playground
• Library for gitlab-ci-verify check helpers

Motivation

Unfortunately, GitLab didn't provide a tool to validate CI configuration for quite a while. Now that changed with the glab CLI providing glab ci lint but it is quite limited and under the hood just calls the new CI Lint API.

Throughout the years quite some tools evolved, but most of them are either outdated, painful to use or install, and basically also provide the lint functionality from the API.

As most of the logic in pipelines is written in shell scripts via the *script attributes these are lacking completely from all tools out there as well as the official lint API.

The goal of gitlab-ci-verify is to provide the stock CI Lint functionality plus shellcheck. Completed in the future some rules to lint that common patterns are working as intended by GitLab and void them from being pushed and leading to unexpected behavior.

Contributing

I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the configuration
• Submitting a fix
• Proposing new features
• Becoming a maintainer

To get started please read the Contribution Guidelines.

Development

Requirements

• Go
• GNU make
• Python 3.10+

Test

make test-coverage-report

Build

make build

Credits

This whole project wouldn't be possible with the great work of the following libraries/tools:

• Shellcheck by koalaman
• go stdlib
• pflag by spf13