generate-policy-bot-config

This script generates the Policy Bot configuration file.

It looks at all the GitHub Actions workflows in .github/workflows, finds the ones which are triggered on the pull_request or pull_request_target events, and generates a configuration file which requires them to pass if they are triggered. If there are path filters, those are copied to the configuration file.

This is needed because GitHub does not support checkes which are required if triggered. We need to implement it externally.

Usage

We're assuming Policy Bot is already configured and working for your organisation.

Generate a configuration file like this:

Running from a Docker image

We push a Docker image to the GitHub Container Registry:

docker run --rm \
  --volume $(pwd):/work \
  --workdir /work \
  ghcr.io/grafana/generate-policy-bot-config:latest \
  --output /work/.policy.yml \
  --log-level=debug \
  --merge-with=/work/policy.yml \
  .

Semver-tagged images are also available, as is main for the latest commit on the main branch.

These docker images are attested using GitHub Artifact Attestations. You can verify our container images by using the gh CLI:

$ gh attestation verify --repo grafana/generate-policy-bot-config oci://ghcr.io/grafana/generate-policy-bot-config:<tag>
Loaded digest sha256:... for oci://ghcr.io/grafana/generate-policy-bot-config:<sometag>
Loaded 3 attestations from GitHub API
✓ Verification succeeded!

sha256:<sometag> was attested by:
REPO                                PREDICATE_TYPE                  WORKFLOW
grafana/generate-policy-bot-config  https://slsa.dev/provenance/v1  .github/workflows/build.yml@<somref>

Attestations can also be viewed on the attestation page of this repository.

What this lets you do is trace a container image back to a build in this repository. You'll still need to verify the build steps that were used to build the image to ensure that the image is safe to use.

Running from source

go run . --output ../../.policy.yml --log-level=debug --merge-with=policy.yml

Commit .policy.yml to your repository. (Use a different name if your Policy Bot configuration requires it.) If it's not already configured, configure Policy Bot as normal: by setting up a ruleset which has only Policy Bot's check as required for pull requests to be mergeable. This check will act as a proxy for your other workflows.

See --help for more documentation.

Merge with existing configuration

The policy.yml file in this directory contains configuration which is merged with the generated config. This allows us to use any of the features of the Policy Bot beyond the conditional checks that this script generates.

The merge is quite naive: it simply appends the generated configuration to the end of the existing configuration. Since we generate configuration of the form:

policy:
  approval:
    - or:
        - and:
            - workflows here

merging a configuration like:

policy:
  approval:
    - or:
        - some rule here

would result in

policy:
  approval:
    - or:
        - and:
            - workflows here
    - or:
        - some rule here

Which might not be what we want. There is an implicit top-level and condition at the root of the policies, so this would mean that "some rule here" and the workflows would be required. It's not possible to add an alternative to the workflows - say, to add an override.

We've got an ad-hoc capability to address this. The special token MERGE_WITH_GENERATED as the first element of a top-level or group in the the merged configuration will cause the rest of that or group to be merged with the generated part of the configuration. Merging:

policy:
  approval:
    - or:
        - MERGE_WITH_GENERATED
        - some rule here

with the above generated configuration would result in

policy:
  approval:
    - or:
        - and:
            - workflows here
        - some rule here

and so "some rule here", if triggered, will approve the group containing the workflows.

Don't mind the regexes

GitHub Actions uses doublestar-style globs for path filters. Policy Bot takes regular expressions. The conversion between the two is hairy. We use a library to do it. Let it wash over you.