gitlab-compliance 2.0.0

Gitlab automatically generates gitlab documentation from yaml files

gitlab-compliance

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 — the same BDD model as terraform-compliance uses for Terraform plans.

Source code: MaturityBuilder/gitlab-compliance.

• 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.