| github-token | GitHub token for PR analysis and comments. Defaults to the automatic workflow token. | no | ${{ github.token }} |
| risk-threshold | Block the PR if the risk score exceeds this value (0-100). | no | 70 |
| warn-threshold | Add a warning if the risk score exceeds this value. Defaults to risk-threshold minus 15. | no | "" |
| health-check-urls | Comma-separated URLs to health-check before scoring (omit for risk-only mode). | no | "" |
| fail-mode | Error mode when Trailhead fails. Default is env-aware: production=closed, others=open. | no | "" |
| override-fail-mode | Governed override for fail-mode (open|closed). Requires reason/owner/ticket/expiry inputs. | no | "" |
| override-risk-threshold | Governed override for risk-threshold (0-100). Requires reason/owner/ticket/expiry inputs. | no | "" |
| override-warn-threshold | Governed override for warn-threshold (0-100). Requires reason/owner/ticket/expiry inputs. | no | "" |
| override-reason | Required when any override is set. Human-readable reason for temporary policy override. | no | "" |
| override-owner | Required when any override is set. Owner accountable for the override. | no | "" |
| override-ticket | Required when any override is set. Linked change ticket (Jira/GitHub issue/etc.). | no | "" |
| override-expires-at | Required when any override is set. ISO-8601 expiry timestamp for the override. | no | "" |
| self-heal | Attempt to auto-repair failing tests before blocking (requires TRAILHEAD_TEST_FAILURES env). | no | false |
| add-risk-labels | Add risk-level labels (trailhead:low-risk, etc.) to the PR. Requires pull-requests: write. | no | true |
| reviewers-on-risk | Comma-separated GitHub usernames to request review from when decision is warn or block. | no | "" |
| webhook-url | URL to POST evaluation results to (Slack, Discord, or custom endpoint). Omit to disable. | no | "" |
| webhook-events | Comma-separated webhook triggers. Legacy gate decisions: allow, warn, block. Semantic agent events: trailhead.blocked, trailhead.warn_high_risk, trailhead.ready, trailhead.loop_exceeded. | no | warn,block |
| trailhead-api-key | Trailhead Cloud API key — auto-configures evaluation store URL and auth. Replaces evaluation-store-url + evaluation-store-secret for cloud tier. | no | "" |
| evaluation-store-url | URL to POST evaluations for historical trend analysis. Omit to disable (or use trailhead-api-key for Trailhead Cloud). | no | "" |
| evaluation-store-secret | Bearer token for authenticating with the evaluation store endpoint. Not needed when trailhead-api-key is set. | no | "" |
| evaluation-store-retries | Number of retry attempts when POST to evaluation-store-url fails with transient errors (default 3). | no | 3 |
| disable-cloud-upsell | Suppress the Trailhead Cloud upsell/quota footer line in the check summary (shown by default when no trailhead-api-key is set, or when the Cloud API reports quota/billing state). | no | false |
| dora-metrics | Compute DORA-5 metrics (deployment frequency, change failure rate, lead time, FDRT, rework rate) alongside the gate evaluation. | no | false |
| dora-environment | Specific deployment environment to use for DORA metrics (e.g. 'production'). Uses Deployments API when set. | no | "" |
| environment | Target deployment environment. Used for per-environment threshold overrides from .trailhead.yml. | no | "" |
| gate-mode | Gate mode: release-ready (composite CI+risk), advisory (never blocks), or risk-only (v3 compat). Overrides .trailhead.yml gate.mode when set. | no | "" |
| wait-for-checks | Poll GitHub Checks API until required checks complete or timeout. Defaults to true in release-ready mode when gate-mode input is set. | no | "" |
| wait-timeout-minutes | Maximum minutes to wait for required CI checks when wait-for-checks is enabled. | no | 30 |
| ci-manifest-path | Path to ci-manifest.json from a prior workflow job (path-filter skip semantics). See docs/ci-manifest.md. | no | "" |
| ci-external-status-url | URL to fetch external CI status JSON (GitLab/CircleCI webhook store). Supports {sha} placeholder. | no | "" |
| ci-external-status-secret | Bearer token for ci-external-status-url when the status endpoint requires auth. | no | "" |
| gitlab-api-url | GitLab API base URL (default https://gitlab.com/api/v4). Used with gitlab-token and gitlab-project-id. | no | "" |
| gitlab-token | GitLab private token for polling pipeline job status (E17.1). | no | "" |
| gitlab-project-id | GitLab project ID or URL-encoded path for pipeline status polling. | no | "" |
| circleci-token | CircleCI API token for polling workflow job status (E17.2). | no | "" |
| circleci-project-slug | CircleCI project slug (e.g. gh/org/repo) for workflow status polling. | no | "" |
| check-name | GitHub check run name. Defaults to 'Trailhead — Release Ready' in release-ready mode, 'Trailhead' in risk-only mode. | no | "" |
| agent-brief | Agent remediation brief in PR comments: off, collapsed (default for agent PRs), or expanded. Omit to use .trailhead.yml gate.agent_brief or provenance-based default. | no | "" |
| submission-gate | Enable Gate 1 agent submission checks (mock placeholders, artifact integrity, secrets, etc.). Default off; also enable via .trailhead.yml submission.enabled. | no | false |
| security-gate | Enable GitHub Code Scanning alert integration as a risk factor. Set to 'false' to disable. | no | true |
| canary-webhook-secret | HMAC secret for verifying deploy outcome webhooks (Vercel/generic). | no | "" |
| otel-endpoint | OTLP HTTP endpoint to export evaluation spans to (e.g. https://otel.example.com:4318/v1/traces). Omit to disable. | no | "" |
| otel-headers | Auth headers for the OTLP endpoint as key=value pairs, comma-separated. | no | "" |
| api-key | API key for remote enrichment via a Trailhead cloud endpoint. Omit for local-only mode. | no | "" |
| credit-meter-url | Komatik credit-meter-ingest URL for deploy_check billing (e.g. https://<project>.supabase.co/functions/v1/credit-meter-ingest). Also KOMATIK_CREDIT_METER_URL. | no | "" |
| credit-meter-secret | Shared secret for credit-meter-ingest (x-komatik-meter-secret header). Prefer KOMATIK_CREDIT_METER_SECRET env/secret. | no | "" |
| credit-meter-shadow | Record shadow deploy_check credits without debiting balance (default true until credit_apps.enforced for trailhead). | no | true |
| credit-meter-enforce | When true and credit meter returns allowed:false, emit a blocking warning. Does not block the gate unless paired with strict policy (fail-open default). | no | false |
| autofix | When true, commit auto-fixes for autofix-eligible findings (e.g. contract_integrity catalog stubs) to the PR's HEAD branch. Default false = dry-run (plan only, logged). Requires contents:write and a non-fork PR. | no | false |
| cross-repo-token | Token with write access to the repos that OWN dangling cross-repo contract APIs. Enables the contract_integrity cross-repo PR opener (ADR-010) to open declaration PRs in the owning repo. The default GITHUB_TOKEN is scoped to the current repo only, so a PAT or GitHub App token is required. Without it the opener stays in dry-run. | no | "" |
| cross-repo-opener | Set to 'false' to disable the cross-repo PR opener even when configured. Default enabled (the opener still requires submission.contract_integrity.cross_repo_opener.enabled, an api_owners map, and a cross-repo-token to actually open PRs). | no | true |
| evaluate-pr | Evaluate a specific PR by number instead of the triggering event's PR. Enables backfill / on-demand re-evaluation of historical PRs (open, closed, or merged) with the current engine version — driven from workflow_dispatch or a direct `node dist/index.js` run. The diff, author history, age, and provenance are fetched from the GitHub API by PR number, so no checkout of the PR is required. In this mode the gate only scores and persists the evaluation; PR comments, labels, reviewer requests, self-heal, and autofix are skipped. Requires github-token. | no | "" |