layout: home title: Overview permalink: /

Gitlab Compliance

Gitlab Compliance is a BDD compliance testing and documentation generation toolkit for GitLab CI/CD pipelines and project settings. It runs Gherkin policies against `.gitlab-ci.yml` and optional GitLab API settings. You can also generate markdown documentation for your Gitlab pipelines.

Source code - coming soon: MaturityBuilder/gitlab-compliance.

Get started

Get started{ .md-button .md-button-primary } Usage{ .md-button } BDD grammar{ .md-button }

gitlab-compliance supports two core workflows from the same pipeline YAML:

pip install gitlab-compliance

# Validate pipeline configuration against policies
gitlab-compliance check -f policies/ -p .gitlab-ci.yml

# Generate pipeline documentation (filter and group output as needed)
gitlab-compliance generate -i .gitlab-ci.yml --format swagger-markdown -o pipeline-reference.md
gitlab-compliance generate -i .gitlab-ci.yml --exclude variables,image --group-by stage

See Usage for the full CLI (including demos) and Generate pipeline documentation for output formats, --exclude, and --group-by.

• compliance: Ensure pipeline YAML and project settings follow your security standards and custom policies
• behaviour driven development: Policies are readable Gherkin scenarios that developers and security teams share
• portable: Install from pip. See Installation
• pre-merge: Validate configuration before changes land on protected branches
• YAML and API: Offline checks against pipeline files; optional GitLab API checks for project settings and CI variables
• easy to integrate: Run in GitLab CI or local git hooks
• segregation of duty: Keep policy packs in a separate repository or OCI registry
• documentation: Generate Markdown or HTML reference docs from .gitlab-ci.yml

Idea

gitlab-compliance focuses on negative testing — catching misconfigurations and policy violations — rather than proving that a job runs successfully end to end.

GitLab CI pipelines are defined in YAML that composes jobs, includes, variables, and workflow rules. What was missing is a lightweight way to assert that this configuration follows organizational standards before merge. GitLab offers native compliance features in higher tiers; gitlab-compliance provides an open, portable alternative inspired by terraform-compliance and Conftest.

For example, a policy might require that no job uses a floating latest image tag:

if a job defines an image, it must not use the :latest tag

translates into:

Given I have any job defined
When it has image
Then its image must not match ":latest$"

The image value comes from your pipeline YAML:

scan:
  image: python:3.12
build:
  image: docker:latest   # violates the policy above

In CI, this scenario runs against .gitlab-ci.yml (and resolved local includes) so merge requests cannot introduce violations.

See Examples for more sample use cases.

Supporting / Requirements

• Python: 3.12 (see Installing via pip)
• Pipeline file: .gitlab-ci.yml or another path passed with -p
• API checks (optional): GitLab token plus --project or --group for settings and CI variable policies

Full CLI options: Usage. Step grammar: BDD Reference.

How can you support the project?

Contributions are welcome — see Contributing.