Skip to content

GitHub Actions

Run gitlab-compliance in GitHub Actions to gate pull requests and default-branch builds. This repository also ships workflows for pre-commit, Danger PR review, tests, documentation, release-please, and tag-gated PyPI and Docker publish.

Quick start (consumer projects)

Install via pip

compliance:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
      with:
        python-version: "3.12"
    - run: pip install gitlab-compliance
    - run: gitlab-compliance check -f policies/security -p .gitlab-ci.yml

Full example: examples/example-github-actions/compliance-pip.yml.

Run via container

compliance:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
    - run: |
        docker run --rm -v "$PWD:/work" -w /work \
          maturitybuilder/gitlab-compliance:latest \
          compliance -f policies/security -p .gitlab-ci.yml

Full example: examples/example-github-actions/compliance-container.yml.

Copy policies first:

cp -r examples/example-policies/security policies/security

Repository workflows

Pre-commit (local and CI)

Install hooks after cloning:

poetry install
poetry run pre-commit install
poetry run pre-commit run --all-files

Configuration: .pre-commit-config.yaml.

Danger PR review

dangerfile.py warns on:

  • Very large PRs
  • src/ changes without tests/ or docs/ updates
  • CI file changes (links to this guide)
  • Non-conventional PR titles (informational)

Enable Settings → Actions → General → Workflow permissions → Read and write so GITHUB_TOKEN can post PR comments.

Release (release-please, PyPI, Docker Hub)

Releases are automated with release-please. Configuration lives in release-please-config.json and .release-please-manifest.json.

Release flow

  1. Merge conventional commits (feat:, fix:, BREAKING CHANGE:) to main.
  2. The release-please job opens or updates a Release PR (version bump in pyproject.toml and src/__init__.py, plus CHANGELOG.md).
  3. Merge the Release PR — release-please creates a GitHub Release and tag vX.Y.Z.
  4. The tag push runs test, then publish-pypi and publish-docker in parallel.

If CI does not run on release-please PRs, switch the release-please step to a personal access token (MY_RELEASE_PLEASE_TOKEN) per the release-please-action credentials docs.

One-time publish setup

PyPI (OIDC trusted publishing)

PyPI publish uses trusted publishing (OIDC) — no long-lived PYPI_TOKEN secret is required.

  1. On PyPI, add a trusted publisher for GitHub Actions:
Field Value
Owner MaturityBuilder
Repository gitlab-compliance
Workflow name release.yml
Environment name pypi
  1. In GitHub Settings → Environments, create a pypi environment (optional but recommended for deployment protection).

The publish-pypi job runs poetry build, then uploads with pypa/gh-action-pypi-publish using id-token: write.

Docker Hub

Add these in GitHub Settings → Secrets and variables → Actions:

  • DOCKERHUB_USERNAME: Variable
  • Docker Hub username or org name (maturitybuilder)
  • DOCKERHUB_TOKEN: Secret
  • Docker Hub access token with Read & Write scope (create token)

Docker publish tags semver releases as X.Y.Z, X.Y, and latest (only on tagged releases, not on every main push). Builds include provenance and SBOM attestations.

Docker build and scan

Image: maturitybuilder/gitlab-compliance

The build-and-scan job in docker.yml runs on pull requests and pushes to main / master:

  1. Builds from dockerfile (no push)
  2. Runs Trivy filesystem and image scans (CRITICAL, HIGH severities fail the job)
  3. Uploads image scan SARIF to the Security tab
  4. Smoke-tests gitlab-compliance --help

Docker Hub push happens only from the publish-docker job in release.yml when a semver tag is created.

API-backed policies

For GitLab project settings and CI variable checks, pass a token and project path:

- run: |
    gitlab-compliance check \
      -f policies/security \
      -p .gitlab-ci.yml \
      --project my-group/my-project \
      --strict
  env:
    GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}