Skip to content
GONATURELLE
GitHub Actions logoCI/CD

GONATURELLE for GitHub Actions

Gate pull requests with gonaturelle/gate-action@v2: fast path on every push, full suite on pull requests, a PR comment with regression diffs, and a required status check.

Start 14-day trialSetup steps
gonaturelle/gate-action@v2
.github/workflows/gonaturelle.yml
name: gonaturelle-gate
on:
  push:
    branches-ignore: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'
permissions:
  contents: read
  pull-requests: write
  checks: write
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - uses: gonaturelle/gate-action@v2
        with:
          suite: gonaturelle.yml
          mode: ${{ github.event_name == 'push' && 'fast-path' || 'full' }}
          baseline: main
          comment: true
          junit-path: reports/gonaturelle.xml
          api-key: ${{ secrets.GONATURELLE_API_KEY }}

The GitHub Action is the most common way teams adopt GONATURELLE, because it puts evaluation where prompt changes are already reviewed. gonaturelle/gate-action@v2 installs the CLI, reads your gonaturelle.yml suite file, runs the selected mode against the branch, compares results with the baseline branch and reports back through three GitHub surfaces: a check run with pass or fail status, a pull request comment, and a JUnit XML artifact.

The fast path runs the 20 most critical cases with three judges and is designed for every push; its median wall-clock time is 74 seconds (GONATURELLE platform telemetry, Q3 2026). The full suite runs on pull requests targeting main, on merges and on a nightly schedule, sharded across GONATURELLE runners so your GitHub-hosted runner mostly waits on results rather than executing cases. The PR comment lists each regressed case with the failing assertion, judge score deltas against their tolerance, token cost per case and p95 latency, and it is updated in place on each push instead of adding a new comment.

The workflow needs pull-requests: write permission to comment and contents: read to check out the code. The API key lives in an Actions secret. To make the gate binding, add the gonaturelle/gate check to required status checks in branch protection or a repository ruleset; overrides are then visible in GitHub and logged in GONATURELLE's audit trail with the approver's identity.

What you can test with GitHub Actions.

Mode selection by event

Use the GitHub expression syntax to choose fast-path on push and full on pull_request, or let the action decide from changed paths: prompt and tool-schema changes trigger the full suite.

PR comment with regression diffs

One comment per pull request, updated on each push, naming regressed cases, failing assertions, the prompt diff, judge deltas and token cost impact. No raw inputs or outputs are posted.

Required status check

The gonaturelle/gate check run can be required in branch protection or rulesets, so a regression blocks the merge button rather than relying on reviewers to read a comment.

JUnit and step summary

Results are written as JUnit XML for test reporters and as a job summary in Markdown, so the outcome is visible without leaving the Actions run page.

Set up in 5 steps.

Most teams have a first suite running against GitHub Actions in under an hour, then add the CI gate.

Get an API key
  1. 01

    Create an GONATURELLE API key with the ci role and store it as the GONATURELLE_API_KEY repository or organization secret.

  2. 02

    Commit an gonaturelle.yml suite file that pins pack versions, private suites, assertions and thresholds.

  3. 03

    Add .github/workflows/gonaturelle.yml with the gate action, granting contents: read and pull-requests: write permissions.

  4. 04

    Open a pull request that changes a prompt to confirm the comment and check run appear, then promote main as the baseline.

  5. 05

    Mark gonaturelle/gate as a required status check in branch protection or a repository ruleset.

GitHub Actions integration FAQ

Does the action run our agent on GitHub's runner or on GONATURELLE?

Your agent code runs where your workflow runs, because it is your code and your credentials. GONATURELLE distributes cases, runs judges and stores results. For agents that must not run on GitHub-hosted runners, use self-hosted runners inside your network.

Will pull requests from forks have access to the secret?

No. GitHub does not pass secrets to workflows triggered by pull requests from forks, so the gate will not run there by default. Most regulated teams work in private repositories where this does not arise.

How do we avoid comment noise on busy pull requests?

The bot edits a single comment per pull request. You can also set comment: on-failure so it only posts when the gate fails or a warning threshold is crossed.

Related integrations

All integrations

Stop testing regulated agents on generic prompts.

Run your agent against 100 industry-standard clinical or financial edge cases in 5 minutes. 14-day free production trial, no card.

Start free trialBook a technical demo