Skip to content

GitHub Action

Jump to bottom
Allen Byrd edited this page Jun 2, 2026 · 1 revision

GitHub Action

RegRails ships a reusable composite GitHub Action that drops the deterministic FERPA + Title IV guardrail in front of an automated workflow. In one uses: line it installs regrails from PyPI, consults the guardrail, fails the job on a block / escalate_human_review outcome, and writes a SARIF report — so an automated "advisor" pipeline cannot ship a prohibited disclosure or a high-stakes aid determination without a human.

The action lives at docs/action/ in the repo and is referenced as Polycentric-Labs/regrails/docs/action@<ref>.

Pages: CLI Reference · Web Platform · MCP Server · Exports — OSCAL and SARIF

What it does

It is a composite action with three steps:

  1. Install regrails — python -m pip install "regrails==<version>" (the engine is offline; no API key).
  2. Consult the guardrail — runs regrails decide twice: once to JSON (to read outcome + risk_tier into step outputs), once with --format sarif to write the SARIF report.
  3. Enforce the gate — if the decision outcome is in the fail-on list, it emits a ::error:: annotation and exits non-zero, failing the job.

Because the engine is deterministic and offline, the gate is reproducible and needs no secrets.

Inputs

Input Required Default Meaning
query yes — The user-facing query the AI workflow is about to act on.
topic no unknown disclosure | aid_status | other | unknown.
data no "" Comma-separated data_requested items (e.g. gpa,transcript).
extra-args no "" Extra flags passed verbatim to regrails decide (e.g. --aid-determination --in-default).
fail-on no block,escalate_human_review Comma-separated outcomes that fail the job.
version no 0.4.0 regrails version to install from PyPI.
sarif-path no regrails.sarif Where to write the SARIF report.

Outputs

Output Meaning
outcome The GuardrailDecision outcome.
risk-tier The decision's risk tier.

Usage

Add one step to a workflow in your own repo:

- name: RegRails gate
  uses: Polycentric-Labs/regrails/docs/action@v0.4.0
  with:
    query: "I defaulted on a loan a while back. Am I still eligible for aid this year?"
    topic: "aid_status"
    extra-args: "--aid-determination --in-default"

This high-stakes Title IV query returns escalate_human_review, which is in the default fail-on list — so the step fails the job, and the automated pipeline cannot proceed without a human.

Full workflow example

From docs/action/workflow-example.yml — copy it into .github/workflows/ in your own repo:

name: example — RegRails guardrail gate

on: [workflow_dispatch]

permissions:
  contents: read

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      # A high-stakes Title IV query: a student in loan default asking about
      # eligibility. RegRails returns escalate_human_review -> this FAILS the job,
      # so an automated "advisor" pipeline cannot ship the answer without a human.
      - name: RegRails gate
        uses: Polycentric-Labs/regrails/docs/action@v0.4.0
        with:
          query: "I defaulted on a loan a while back. Am I still eligible for aid this year?"
          topic: "aid_status"
          extra-args: "--aid-determination --in-default"

      # If the gate passes, upload the SARIF so it renders in code-scanning.
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: regrails.sarif

The if: always() upload ensures the SARIF renders in code-scanning whether the gate passed or failed, so each blocked/escalated decision shows up as a finding (with its CFR citation and risk tier) just like a code vulnerability. See Exports — OSCAL and SARIF for the SARIF shape.

Notes

  • Pin the ref to a release tag (@v0.4.0) so the action's behavior, the installed regrails version default, and the documented uses: path stay in lockstep. To gate against a different package version, also set the version input.
  • Tune fail-on to your tolerance — e.g. add escalate_consent to also fail on consent-required disclosures, or narrow it if you only want to hard-stop on block.
  • The action requires only contents: read; the SARIF upload step uses github/codeql-action/upload-sarif (which needs security-events: write if you scope permissions per job).

RegRails is a proof-of-concept, not a compliance product and not legal advice. The Action gates a pipeline on the deterministic engine; it does not certify compliance. Synthetic data only.

Clone this wiki locally