| mode | Action mode:
- "report" (default): surface BDD stories as PR comment + HTML artifact
- "review": generate an Evidence Review of the PR's changes — correlate the run to the diff and
band changed code as uncovered / weak / strong. Requires a run JSON (see run-json).
- "gate-release": verify a release candidate matches the dev test baseline
- "deploy": record a deployment to the environment ledger
- "ingest": push the run's StoryReport to a cloud ingest endpoint (requires api-key).
The run URL and the scope the change implies are written to the job summary;
set ingest-gate to also block on the org's release policy. On a pull request the
gate's verdict is posted as the PR comment and annotated on the Checks tab before
the step fails, so a blocked developer reads the reasons rather than a bare red X.
- "publish-run": commit the run JSON to an orphan branch (runs-branch) so other
repos — e.g. a multi-repo docs hub — can
fetch it from a stable raw.githubusercontent.com URL. Requires `contents: write`.
| no | report |
| report-dir | Directory containing or receiving generated reports | no | reports |
| output-name | Base filename for reports (without extension) | no | test-results |
| raw-run | Path to raw run JSON (auto-detected if not set) | no | .executable-stories/raw-run.json |
| formatter-version | Version of executable-stories binary to download (latest or semver) | no | latest |
| artifact-name | Name for the uploaded GitHub artifact | no | executable-stories-report |
| comment-title | Header text for the PR comment | no | Executable Stories |
| host-images | How to handle screenshots and videos so GitHub can show them in the PR comment.
A comment cannot fetch a `data:` URI or a relative path, and both shapes reach
the markdown — inline base64 from a reporter, `assets/…` from `--asset-mode copy`.
- "false" (default): label them (`📎 alt (see HTML report)`), which is honest
where a broken image icon is not. The media stays in the HTML artifact. No
write permissions needed.
- "branch": commit the media to an orphan branch on this repository and rewrite
the markdown to raw.githubusercontent.com URLs, so screenshots render inline
and videos become a link. Files over 10 MB, and any reference resolving
outside the workspace, are skipped with a warning. Requires `contents: write`.
Videos never play inline either way: GitHub builds a player only for media
uploaded through user-attachments, which the API cannot do.
| no | false |
| images-branch | Branch name used when host-images: branch. Holds screenshots and videos. Created as an orphan branch on first use. | no | executable-stories-images |
| gate-dev-run | (gate-release) Path to the dev environment test run to use as baseline | no | — |
| gate-fail-on-regression | (gate-release) Fail if scenarios regressed from dev to RC (default: true) | no | true |
| gate-fail-on-removal | (gate-release) Fail if scenarios in dev are missing from RC (default: true) | no | true |
| gate-fail-on-new | (gate-release) Fail if new scenarios appear in RC not in dev | no | false |
| gate-release-policy | (gate-release) Path to release policy JSON with allowed exceptions | no | — |
| deploy-env | (deploy) Environment name to record the deployment against (e.g. dev, staging, production) | no | — |
| deploy-tag | (deploy) Git tag for this deployment (e.g. v1.2.3) | no | — |
| deploy-ledger | (deploy) Path to deployment ledger JSON | no | .executable-stories/deployments.json |
| run-json | (review mode) Path to the run JSON (raw or canonical) to correlate against the diff. Defaults to raw-run. | no | "" |
| base-ref | (review mode) Base ref to diff against. Defaults to the PR base branch (GITHUB_BASE_REF). | no | "" |
| changed-files | (review mode) Optional precomputed changed-files file (JSON or `git diff --name-status` text). If unset, the action computes it from git. | no | "" |
| fail-on | (review mode) Opt-in gate: 'uncovered' or 'weak' — fail the check when changed code lacks evidence. Default: off. | no | "" |
| min-evidence | (review mode) Opt-in gate: 'weak' | 'moderate' | 'strong' — fail when any claim is below this strength. Default: off. | no | "" |
| runs-branch | (publish-run) Branch the run JSON is committed to. Created as an orphan branch on first use. | no | executable-stories-runs |
| runs-path | (publish-run) Path of the published file within runs-branch. Give each suite its own path if one repo publishes several runs. | no | raw-run.json |
| formatter-binary | Path to a prebuilt executable-stories binary to use instead of downloading from Releases (for dev/testing before release). | no | "" |
| cloud-links | Link the run in Executable Stories Cloud from the PR comment. Off until the
cloud is generally available — the action does not advertise a product you
cannot yet sign up for. Everything else about ingest mode works regardless;
with this off the comment links the workflow run instead.
| no | false |
| api-key | (ingest) Cloud ingest API key (es_…). Store it as a repo/org secret. When unset, ingest mode fails fast. | no | "" |
| ingest-url | (ingest) Base URL of the cloud instance to push runs to. | no | https://app.executablestories.com |
| ingest-gate | (ingest) After pushing, ask the cloud whether this commit is safe to release and fail the step if it is blocked. The policy lives in your organization's settings, not in a file in this repo. On a pull request the verdict is rendered as the PR comment first — same findings, severities and agent prompt as a local Evidence Review — so the reasons reach the developer, not just the job log. A commit with no release recorded says the gate was not evaluated; that is deliberately not reported as a clear verdict, because nothing was checked. | no | false |