Skip to content

CI integration guide

Policyglass fits best as a fast validation step before packaging or deployment.

Basic GitHub or Forgejo Actions step

- name: Install Policyglass
  run: python -m pip install 'https://code.mehalter.com/api/packages/clawlter/pypi/files/policyglass/0.1.1/policyglass-0.1.1-py3-none-any.whl'

- name: Check repository policy
  run: policyglass check . --policy policyglass.yml

Use the exact Forgejo-hosted wheel URL. A different policyglass package already exists on public PyPI, so a bare package-name install is ambiguous.

Dogfooding in the Policyglass repository

This repository uses Policyglass to validate itself in CI before the editable checkout is installed.

The Forgejo and GitHub workflows both follow this pattern:

- name: Install latest released Policyglass
  run: python scripts/install_latest_policyglass_release.py --install-dir .tools/policyglass-release

- name: Validate repository policy
  run: .tools/policyglass-release/bin/policyglass check . --policy policies/repository.yml

Why this is useful:

  • the validation step exercises the published package, not an unreleased working tree build
  • the policy file lives with the repository and documents what the project considers required to ship
  • the quality pipeline can still install the checkout separately afterward for linting, tests, docs, and packaging

The release workflow extends the same pattern after python -m build by generating dist/checksums.txt and validating the built bundle with policies/release-artifacts.yml.

Validate build artifacts

- name: Build package
  run: python -m build

- name: Generate checksums file
  run: |
    find dist -maxdepth 1 -type f -print0 | sort -z | xargs -0 sha256sum > dist/checksums.txt

- name: Check release bundle
  run: policyglass check dist --policy examples/release-artifact-policy.yml

Capture JSON output

- name: Generate machine-readable report
  run: policyglass check . --policy policyglass.yml --format json > policyglass-report.json

Good CI usage patterns

  • keep policy files in the repository
  • scope policies to a clear use case instead of making one enormous ruleset
  • use JSON output when another step needs to parse findings
  • keep ignore rules narrow so they do not silently hide important paths

What to avoid

  • using overly broad regexes that match everything
  • treating Policyglass as a complete secret scanner
  • relying on it alone for release security review