Index

gitlab-compliance (PyPI package gitlab-compliance) is a lightweight, security and compliance focused test framework for GitLab CI/CD. It runs Gherkin policies against .gitlab-ci.yml and optional GitLab API settings. You can also generate markdown documentation for your gitlab pipelines.

— the same BDD model as terraform-compliance uses for Terraform plans. Source code: MaturityBuilder/gitlab-compliance.

Get started¶

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 compliance options 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.