SigillumDashboard shell
GITHUB ACTION

Maintainer runbook

Github Action

Sigillum already has a first-party hosted PR check. This page now acts as the maintainer-facing setup surface: what to wire, what to expect on a pull request, and which proof artifacts should always appear after a live run.

Action liveHosted checkPR diff inspectionReceipt-backed proof

Maintainer surface

What this page owns today

These cards translate the live Sigillum product state into a maintainer/admin runbook without exposing raw payloads or editing the payment path.

Adoption

Reusable workflow ready

The action runtime is already proven, and the reusable workflow path is now the preferred rollout model for downstream repositories that want less YAML drift.

Proof

Receipt URL required

Every successful PR check should end with a persisted receipt ID, payment reference, recommendation, and `Sigillum Risk Score` that link back into the public proof surfaces.

Control

Policy knobs still thin

Today the workflow can fail on warn. Maintainers still need clearer gating controls for recommendation thresholds, score ceilings, and comment behavior.

Primary runbook

Reference maintainer rollout

Use this sequence when enabling Sigillum in a new repository. It keeps the GitHub workflow surface aligned with the existing hosted payment flow and receipt registry.

1

Wire the check into pull requests

The first production-ready move is a checked-in workflow file that runs on pull requests and points at either the reusable workflow or the first-party Sigillum action.

  • Use the hosted Sigillum base URL rather than a local app.
  • Keep the check on pull_request first before widening to other GitHub events.
  • Make the workflow readable enough that repo admins can audit what secrets and gates it uses.
2

Provide buyer payment credentials server-side

Live inspect flows still need the buyer-side x402 payment credentials. Maintainers should treat those as repository or organization secrets, never inline configuration.

  • Store the buyer private key in GitHub Actions secrets only.
  • Keep network and RPC values explicit so the workflow is anchored to Arc testnet.
  • Document the payment reference as the required proof object, with Arc hash only when real.
3

Expect PR-native proof after every run

A production-ready maintainer experience should not stop at a green step. Reviewers need the Sigillum outcome, proof link, and payment trace right in the PR context.

  • The job summary should show recommendation, score, decision, receipt, and payment reference.
  • A sticky PR comment mode is the next polish layer so reviewers do not need to open logs.
  • Receipt links should match what appears on the dashboard and receipt page exactly.

Reference snippets

Copy-safe examples

Keep these snippets aligned with the current hosted Sigillum flow and existing workflow inputs. They are admin guidance only, not mock runtime data.

Reference workflow inputs

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  sigillum_base_url: https://usesigillum.vercel.app
  fail_on_warn: false
  save_receipt_json: true

Reusable workflow adoption path

jobs:
  sigillum:
    uses: Devendurance/sigillum/.github/workflows/sigillum-pr-check-reusable.yml@main
    with:
      comment_mode: sticky
      fail_on_warn: false
      max_risk_score: "85"
      max_allowed_recommendation: warn
      max_quote_amount_usdc: "0.000500"
    secrets:
      x402_buyer_private_key: ${{ secrets.X402_BUYER_PRIVATE_KEY }}
      x402_rpc_url: ${{ secrets.X402_RPC_URL }}

Secrets the repo admin should already have

env:
  X402_BUYER_PRIVATE_KEY: ${{ secrets.X402_BUYER_PRIVATE_KEY }}
  X402_NETWORK: arcTestnet
  X402_RPC_URL: ${{ secrets.X402_RPC_URL }}

Admin checks

Maintainer acceptance checks

Before rolling the action across repos, these are the checks the admin surface should make obvious.

ProofEvery successful run should expose a receipt URL that opens a real persisted Sigillum receipt and matches the recommendation shown in the GitHub check.
PolicyDo not stop at `fail_on_warn` alone. Repos will want recommendation and score-based controls before maintainers trust the workflow as a branch gate.
SecretsKeep buyer payment credentials and RPC values in GitHub secrets or org secrets only. The dashboard should stay an admin guide, not a place where secrets are entered.
AdoptionA reusable workflow variant is still the cleanest next step for multi-repo rollout, because it removes hand-built YAML drift without changing the hosted inspect path.

Admin metrics

What maintainers should watch

These are the operational proof points the current GitHub, policy, and pricing surfaces should make easy to audit before expanding scope.

Required result

Pass / warn / block

Branch protection should map cleanly to the Sigillum outcome. The check must never look green while hiding a blocking receipt.

Expected outputs

7 proof fields

Receipt ID, receipt URL, recommendation, risk score, agent decision, payment reference, and paid amount should all remain visible to maintainers.

Live flow

Quote -> 402 -> receipt

The action must stay on the same hosted payment and inspection path as the CLI and dashboard, not a private CI-only shortcut.

Operator posture

Secrets + branch rules

The repo admin experience is mostly about correct secret wiring, review policy, and making receipt links easy to trust during code review.

Canonical docs

/docs/github-action

The dashboard page is now the runbook surface. The full long-form source of truth for setup, policy, and outputs should live in the public docs route.

Useful links

Stay inside persisted proof

These routes let maintainers move from runbook guidance back into live proof without hunting through internal docs.

Agent dashboardTimeline viewCanonical docsPolicy configPricing admin