← Guides

Add ponens to CI / your PRs

You'll end up with a comment on every pull request — the goal's met / governed / certified status, the declared gaps, and a one-click interactive viewer — plus the governed axis wired as a blocking PASS/FAIL check, all offline.

1. Ship a trace with the change

The agent emits the trace during its session and commits it alongside the code. The default location the action looks for is .ponens/trace.json:

ponens emit -o .ponens/trace.json
git add .ponens/trace.json

2. Add the pr-trace action

Drop a workflow in .github/workflows/ponens.yml. The pr-trace action summarizes the trace on the PR and uploads the viewer:

name: ponens
on: pull_request

permissions:
  contents: read
  pull-requests: write          # to post the comment

jobs:
  ponens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: imandra-ai/ponens/.github/actions/pr-trace@main
        with:
          trace-path: .ponens/trace.json

If no trace is present, the action no-ops quietly — it never fails a build just for being absent.

3. Gate on the governed axis (optional)

To make the governed verdict a required check, add a step that fails when the trace violates a policy the goal is subject to:

      - name: Install ponens
        run: pip install "ponens @ git+https://github.com/imandra-ai/ponens.git#subdirectory=cli"
      - name: Governed gate
        run: ponens trace check .ponens/trace.json   # non-zero exit on FAIL

This is a real gate — deterministic, offline, no model calls. Policies block by default; a disable or a waiver is recorded on the trace, never silent. Pick the policies it enforces in the govern-a-repo guide.

Met and certified are reported but not gated here: met follows automatically from the evidence, and certified is a human sign-off that belongs in review, not in an automated check.

What the reviewer sees

• the goal's met / governed / certified status, inline on the PR;
• the residual surface — the gaps the author declared;
• a link to the interactive viewer (uploaded as a build artifact).

That's the whole point: the record shows up where review already happens, so nobody has to go find it.

Next: how a reviewer uses it →