| semfora-key | Your Semfora license key (from the semfora.ai dashboard). Required — the action verifies it before running. Store it as a repository or organization secret. | yes | — |
| base | Base sha to gate against. Defaults to the pull request base sha from the workflow event. | no | — |
| poll-timeout-minutes | How long to wait for the cloud gate run to finish before failing the step. First-time indexes of very large repos may need more. | no | 20 |
| api-url | Semfora API base (self-hosted deployments only). | no | https://semfora.ai |
| required-reviewers | Comma/space-separated GitHub usernames (and org/team slugs, e.g. "my-org/platform") to request as reviewers on the PR. Users must be contributors on the repo (collaborators) — each entry is validated and people without repo access are skipped with a warning. Requires the workflow to grant `pull-requests: write`. | no | — |
| request-reviewers-on | When to file the review request: "fail" (default — only when the gate finds policy errors), "always", or "never". | no | fail |
| require-approval | "true" — a policy failure only passes once one of the required reviewers approves the PR at its current head commit (stale approvals don't count). "admin" — the approval must come from someone with admin permission on the repo. Add the `pull_request_review: [submitted]` trigger so the check re-runs when they approve; mark the check required in branch protection to make this binding. | no | false |
| require-reason | "true" — a failing gate stays red until someone explains the change in a PR comment mentioning @semfora (at least 10 characters of reason; accepted from the PR author or a repo collaborator, never bots). The comment re-runs the gate via the issue_comment trigger (add it to this workflow's `on:` and grant `actions: write`), the check turns green, and the reason is recorded on semfora.ai together with the denied domains and quality deltas it covers. Combinable with require-approval — then a failure needs the approval AND the reason. Off by default. | no | false |
| line-comments | "true" (default) — annotate the exact lines the policy rules hit, attached to the single gate review (deduplicated across runs; hits outside the diff stay in the gate report comment). Requires `pull-requests: write`. | no | true |
| request-changes | "true" (default) — while the policy verdict is fail, the gate review is submitted as Changes Requested (one line naming the restricted domains), and dismissed automatically once the gate passes or the failure is waived. Requires `pull-requests: write`. | no | true |
| facts | "on" (default) — the report comment includes the "Facts introduced" section: AST-proven properties this change adds (empty catch handlers, returns in finally, exit-free loops, per-iteration IO, identical branches, self-comparisons, literal if-conditions, discarded async promises…), AI-triaged server-side so receiver-type misreads and test-scaffolding noise stay hidden. "off" removes the section. | no | on |
| pr-comment | Post the gate report as a sticky PR comment (edited in place on each run): linked findings, the domains the PR touches (colored to match the semfora.ai dashboard), the measured quality impact, and the generated graphs. "on-findings" (default — comment when there are errors or warnings, and keep refreshing an existing comment), "always", or "never". Requires `pull-requests: write`. | no | on-findings |
| github-token | Token for the reviewer API calls. Defaults to the workflow token; only needed explicitly if you want reviewer requests to come from a bot/app identity. | no | ${{ github.token }} |