CI Integration

This guide shows how to trigger a suite run from CI and fail the pipeline on bad verdicts.

Prerequisites

Pro plan with API keys enabled
Existing suite configured for deployment validation
ONCHAINPROBE_API_KEY stored in CI secret store
SUITE_ID for the suite that must pass before deploying

GitHub Action

The fastest way to integrate OnchainProbe into CI. The official GitHub Action handles triggering, polling, and verdict checking in one step.

Quick start

- uses: onchainprobe/action@v1
  with:
    api-key: ${{ secrets.ONCHAINPROBE_API_KEY }}
    suite-id: <your-suite-id>

Single Suite
Batch Mode

Use a single suite when one gate must pass for the workflow to continue.

name: rpc-regression-gate
on:
  push:
    branches: [main]
  pull_request:
jobs:
  rpc-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: onchainprobe/action@v1
        id: probe
        with:
          api-key: ${{ secrets.ONCHAINPROBE_API_KEY }}
          suite-id: <your-suite-id>
          timeout: '600'
          poll-interval: '15'

Use batch mode to run every suite for a chain that matches a tag.

- uses: onchainprobe/action@v1
  with:
    api-key: ${{ secrets.ONCHAINPROBE_API_KEY }}
    chain-id: <your-chain-id>
    tag: ci
    fail-on-warn: 'true'

Inputs

Input	Required	Default	Description
`api-key`	Yes		OnchainProbe API key
`suite-id`	No		Suite ID for single suite mode
`chain-id`	No		Chain ID for batch mode
`tag`	No	`ci`	Batch tag filter
`api-url`	No	`https://api.onchainprobe.com`	API base URL
`timeout`	No	`300`	Max wait seconds
`poll-interval`	No	`10`	Seconds between polls
`compare-reference`	No	`false`	Compare against a reference endpoint
`compare-baseline`	No	`auto`	Compare against a baseline run: `auto`, `skip`, or a run ID
`fail-on-warn`	No	`false`	Treat `warn` as failure
`comment`	No	`true`	Post or update a PR comment
`github-token`	No	`${{ github.token }}`	Token for PR comments

Outputs

Output	Description
`verdict`	Final verdict
`run-id`	Run or batch ID
`run-url`	Dashboard URL
`exit-code`	OnchainProbe exit code
`markdown-summary`	Markdown summary

Shell Script Alternative

If you cannot use the GitHub Action, the same flow works from any CI system using curl and jq.

The CI flow is a simple four-step loop: trigger, wait, check, exit.

Trigger run
Poll until terminal status
Fetch verdict
Exit with verdict exit_code

Trigger a run

Start by kicking off a run for your gate suite.

RUN_ID=$(curl -sS -X POST "https://api.onchainprobe.com/v1/suites/$SUITE_ID/runs" \
  -H "Authorization: Bearer $ONCHAINPROBE_API_KEY" \
  -H "Content-Type: application/json" | jq -r '.id')

echo "run_id=$RUN_ID"

Poll run status

Runs execute asynchronously. Poll until the run reaches a terminal state.

while true; do
  STATUS=$(curl -sS "https://api.onchainprobe.com/v1/runs/$RUN_ID" \
    -H "Authorization: Bearer $ONCHAINPROBE_API_KEY" | jq -r '.status')

  echo "status=$STATUS"

  case "$STATUS" in
    success|failed|partial|timeout|infra_failed|superseded)
      break
      ;;
  esac

  sleep 10
done

Gate on verdict

Once the run completes, fetch the verdict and use its exit code to pass or fail the pipeline.

EXIT_CODE=$(curl -sS "https://api.onchainprobe.com/v1/runs/$RUN_ID/verdict" \
  -H "Authorization: Bearer $ONCHAINPROBE_API_KEY" | jq -r '.exit_code')

SUMMARY=$(curl -sS "https://api.onchainprobe.com/v1/runs/$RUN_ID/verdict" \
  -H "Authorization: Bearer $ONCHAINPROBE_API_KEY" | jq -r '.markdown_summary')

echo "$SUMMARY"
exit "$EXIT_CODE"

GitHub Actions workflow using shell scripts

If you need to keep shell control but still run in GitHub Actions, this workflow wraps the same curl and jq flow.

name: rpc-regression-gate

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  onchainprobe-gate:
    runs-on: ubuntu-latest
    env:
      ONCHAINPROBE_API_KEY: ${{ secrets.ONCHAINPROBE_API_KEY }}
      SUITE_ID: a7c9ebf2-6b8d-4a0c-ce5f-7d9b1f3a5c6d

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install jq
        run: sudo apt-get update && sudo apt-get install -y jq

      - name: Trigger suite run
        id: trigger
        run: |
          RUN_ID=$(curl -sS -X POST "https://api.onchainprobe.com/v1/suites/$SUITE_ID/runs" \
            -H "Authorization: Bearer $ONCHAINPROBE_API_KEY" \
            -H "Content-Type: application/json" | jq -r '.id')
          echo "RUN_ID=$RUN_ID" >> $GITHUB_ENV

      - name: Wait for completion
        run: |
          for i in {1..60}; do
            STATUS=$(curl -sS "https://api.onchainprobe.com/v1/runs/$RUN_ID" \
              -H "Authorization: Bearer $ONCHAINPROBE_API_KEY" | jq -r '.status')
            echo "status=$STATUS"
            case "$STATUS" in
              success|failed|partial|timeout|infra_failed|superseded) break ;;
            esac
            sleep 10
          done

      - name: Enforce verdict
        run: |
          VERDICT=$(curl -sS "https://api.onchainprobe.com/v1/runs/$RUN_ID/verdict" \
            -H "Authorization: Bearer $ONCHAINPROBE_API_KEY")
          echo "$VERDICT" | jq -r '.markdown_summary'
          EXIT_CODE=$(echo "$VERDICT" | jq -r '.exit_code')
          exit "$EXIT_CODE"

Hardening suggestions

For production pipelines, consider these improvements.

add a max wait timeout and fail on timeout
persist run URL as pipeline artifact
call /runs/:runId/samples for debugging on failure
run a smaller smoke suite pre-deploy and deeper suite post-deploy