GitHub Action

Use ota-run/action@v1 when GitHub Actions should publish the GitHub-native view of ota instead of forcing you to wire JSON parsing and artifact upload by hand.

The action stays thin: ota owns diagnosis and receipts, while GitHub Actions owns the workflow boundary and permissions.

• read-only readiness gates for pull requests and pushes
• baseline-aware regression gates against a restored receipt artifact
• outcome-first step summaries and sticky PR comments with explicit next steps
• step summaries and sticky comments from ota’s own markdown renderer
• annotations for findings from ota’s own GitHub renderer
• sticky pull-request comments when enabled
• uploaded JSON output and archived receipt artifacts with baseline or receipt references

• a pull request needs a trustworthy readiness summary in the GitHub UI
• the workflow should fail only on newly introduced blockers instead of all existing debt
• the repo wants ota receipt --json --archive artifacts without hand-written upload steps
• annotations, step summaries, and sticky comments should all reuse ota’s own wording without a separate adapter script
• the workflow should stay small while the repo contract remains the source of truth

The GitHub wrapper should not invent its own summary phrasing.

Use the same ota renderers everywhere so local CLI output, CI summaries, annotations, and pull-request comments all stay aligned.

• use ota annotations --mode doctor --format markdown for repo doctor step summaries and PR comments
• use ota annotations --mode workspace-doctor --format markdown for workspace doctor summaries and PR comments
• use ota annotations --mode receipt-diff --format markdown for baseline compare and regression-gate summaries
• use ota annotations --mode doctor --format github or --mode workspace-doctor --format github for line annotations
• keep wrapper code thin and let ota own the blocker, provenance, and next-step wording

• use ota-run/setup@v1 when later steps in the same job need direct ota commands such as ota run setup, ota run ci, or ota run deploy:cloudflare
• keep ota-run/action@v1 as the GitHub-native reporting layer and ota-run/setup@v1 as the installer/bootstrap layer
• if a later job also needs direct ota commands, run ota-run/setup@v1 in that job too because GitHub Actions jobs do not share installed binaries

The canonical pull-request gate already restores the latest successful artifact named by artifact-name and fails only on newly introduced blockers.

Set artifact-name explicitly when the workflow should pin that receipt artifact name instead of using the default ota-readiness value.

permissions:  actions: read  contents: read  pull-requests: write jobs:  readiness:    runs-on: ubuntu-latest     steps:      - uses: actions/checkout@v5      - uses: actions/setup-node@v5        with:          node-version: '22'       - name: Publish ota readiness        uses: ota-run/action@v1        with:          command: receipt          path: .          archive: true          artifact-name: ota-readiness          github-token: ${{ github.token }}

• use receipt when you want an archive-friendly, read-only repo receipt artifact
• use doctor when you want the richer readiness verdict and primary-blocker surface
• receipt is the better default for CI because it is read-only and durable

• install: always is the default and installs ota for the selected version on every run
• install: never fails closed unless ota is already available on the runner
• ota-version pins the ota release when installer-driven reproducibility matters
• the action supports Linux, macOS, and Windows GitHub Actions runners

• command chooses the ota surface to run and supports receipt or doctor; default: receipt.
• path passes the repo or contract target to ota; default: ..
• baseline passes an explicit receipt baseline to ota receipt --baseline; it supports latest or a receipt JSON file path.
• fail-on-new-blockers adds --fail-on-new-blockers for receipt compares and lets the action block only on newly introduced blocker findings; default: true.
• working-directory controls the directory where the action invokes ota; default: ..
• execution-mode selects native or container execution when the chosen command supports mode-aware output; default: native.
• member passes an optional monorepo member target.
• archive adds --archive when command=receipt; default: true.
• annotate emits GitHub annotations from ota findings; default: true.
• max-annotations caps emitted annotations; default: 20.
• comment-pr creates or updates the sticky pull-request comment; default: true.
• comment-pr-only limits comment behavior to pull-request events; when set to false, the action may also comment on a pull request associated with the current commit; default: true.
• artifact-name sets the uploaded artifact name and the pull-request receipt baseline source; default: ota-readiness.
• artifact-retention-days sets optional artifact retention in days.
• fail-on-error fails the action when the derived action status is blocked; baseline compare gates can still report risky when baseline debt remains but no new blockers were introduced; default: true.
• install controls ota installation behavior and supports always or never; default: always.
• ota-version pins the installer to a specific ota release such as v1.5.0 when reproducibility matters.
• ota-bin overrides the ota binary name or path after installation resolution; path-like values are resolved from working-directory; default: ota.
• output-path chooses where the captured ota JSON payload is written; default: .ota-action-output.json.
• github-token supplies the token used for pull-request baseline restore and sticky comment updates; the canonical pull-request gate expects it.

• ok reports whether ota returned an ok result.
• status exposes the derived action status: ready, risky, or blocked.
• output-path returns the written path to the captured ota JSON output.
• archive-path returns the archived receipt path when receipt --archive produced one.
• baseline-path returns the resolved receipt baseline path when compare mode restored or used one.
• artifact-name returns the uploaded artifact name.
• error-count returns the error count from the ota summary.
• warn-count returns the warning count from the ota summary.
• info-count returns the info count from the ota summary.
• gate-rule returns the active diff gate rule when compare gating ran.
• gate-passed returns whether the active diff gate passed.
• primary-summary returns the primary blocker or top finding summary.

• when the action installs ota, the install directory is added to PATH for later steps in the same job
• that does not cross into a different job
• if another job needs direct ota commands, run ota-run/setup@v1 in that job or install ota directly there

• the action is not a replacement for ota up or ota run
• use the action for GitHub-native reporting around ota
• use direct ota commands when the workflow must actually prepare or execute repo work

The action source, release tags, and copyable workflow examples live in GitHub.