Metadata-Version: 2.4
Name: gitlab-compliance
Version: 2.0.0
Summary: Gitlab automatically generates gitlab documentation from yaml files
License-File: LICENSE
Author: Charlie Smith
Author-email: me@charlieasmith.co.uk
Requires-Python: >=3.12,<3.13
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: behave (>=1.2.6,<2.0.0)
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: idna (==3.15)
Requires-Dist: jq (==1.8.0)
Requires-Dist: loguru (==0.7.0)
Requires-Dist: markdown-analysis (==0.1.5)
Requires-Dist: oras (==0.2.42)
Requires-Dist: oyaml
Requires-Dist: prettytable
Requires-Dist: pytablewriter (==1.2.0)
Requires-Dist: python-gitlab (==7.0.0)
Requires-Dist: pyyaml (==6.0.2)
Requires-Dist: requests (==2.34.2)
Requires-Dist: rich (==14.2.0)
Requires-Dist: semver (==3.0.2)
Requires-Dist: typer (==0.10.0)
Requires-Dist: urllib3 (==2.7.0)
Project-URL: Documentation, https://maturitybuilder.github.io/gitlab-compliance/
Project-URL: Home Page, https://maturitybuilder.github.io/gitlab-compliance/
Project-URL: Repository, https://github.com/MaturityBuilder/gitlab-compliance
Description-Content-Type: text/markdown

# gitlab-compliance

`gitlab-compliance` (PyPI package [`gitlab-compliance`](https://pypi.org/project/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](https://terraform-compliance.com/) uses for Terraform plans.

Source code: [MaturityBuilder/gitlab-compliance](https://github.com/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](installation/index.md)
- **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](https://en.wikipedia.org/wiki/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](https://terraform-compliance.com/) and [Conftest](https://www.conftest.dev/).

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:

```gherkin
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:

```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](examples/index.md) for more sample use cases.

## Supporting / Requirements

- **Python:** 3.12 (see [Installing via pip](installation/pip.md))
- **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](usage/index.md). Step grammar: [BDD Reference](bdd-reference/index.md).

## How can you support the project?

Contributions are welcome — see [Contributing](contributing.md).

