GitHub Actions and PR comments

Reflow’s native CLI integration runs application flows in GitHub Actions and updates one Change Summary comment as preparation and execution proceed. The final comment links a private visual report containing the selected captures and results. A human reviews the evidence and decides whether to merge.

Run the CLI in CI

The public installer supplies the same CLI used locally. Give the job a Reflow connection with run access, the required plugin runtimes and a reachable application with test data. Keep credentials in the job’s private environment or profile.

Once those prerequisites are configured, set REFLOW_BINDINGS_FILE to the job’s private plugin binding file. This is an example shell variable expanded into the --bindings argument below. The execution sequence is:

reflow init
reflow target http://127.0.0.1:3000 --group app-ci --scope device \
  --bindings "$REFLOW_BINDINGS_FILE"
reflow plan
reflow apply --result-file "$RUNNER_TEMP/reflow-apply.json"

Run from the application’s Git checkout and replace the example target and group. init reports runtime requirements; it does not start the application or its database. Use a separate profile and isolated application state for each job.

apply writes progress to stderr and a final report to stdout. The result file records the request and outcome for the reporting integration. --parallelism can overlap independent flows; dependencies and device capacity limit concurrency. An unchanged second apply can reuse completed evidence within the same target session. Changing target creates fresh execution state.

Use a test collection

A collection lets CI run repository tests and tests kept in Reflow together. Select the same collection your team uses locally. With the CLI commands above, add --collection <collection-id> to target; later commands remember it in the job’s private profile. The storage guide covers collection creation and repository registration.

The source integration’s gh-action/action.yml also accepts these inputs:

Input	Use
collection	The application’s collection ID.
cli-path	The installed Reflow executable; defaults to reflow on PATH.
target-url	The running application reachable from this job.
bindings-file	An owner-only JSON file with this runner’s plugin connections.
inputs-file	An optional owner-only JSON file with test inputs.
zero-url	The Zero endpoint when using a custom deployment.

Install the matching Reflow CLI and plugins, start the required application services, and place private configuration files outside the checkout. The action creates a private profile and passes these files to target. PR execution uses a shared group for that repository and pull request; the run-scoped credential must authorize the collection, and the runner must reach its API and Zero service.

On a default-branch push, collection mode updates Reflow’s historical copies from the exact committed repository files. Tests kept in Reflow retain their saved versions. Register the GitHub owner/name with collection-bind before using this mode. Update the Action and CLI together; older inline uploads cannot create a second editable copy of a collection test.

Collection execution does not publish a PR comment by itself. Use the reporting setup below, with evidence from the run you want reviewed.

Keep execution and publication separate

The configured reporting integration uses two jobs:

1. Execute: run PR application code with read-only repository permissions, gather results and export the visual report before cleaning up the fixture.
2. Publish: use trusted publisher code to observe the execution job, read the allowlisted report and update the owned PR comment. This job has the GitHub permissions needed to read Actions artifacts and write PR comments.

The publisher follows preparation, running and evidence stages. It can report an explicitly configured repair step; your agent or workflow supplies that step. The publisher itself does not author or repair flows.

A new trusted PR push updates the same comment for the current head and workflow attempt. Superseded publishers stop. A commit using [skip ci] leaves the existing comment describing its previously linked run.

The native setup/run actions and publisher are supplied through the Reflow source integration. Repository setup must pin that integration and configure its application fixture, credentials and reporting stages. Installing the CLI alone does not install the PR publisher. There is no standalone Marketplace Action release documented here.

Source access and setup recipe

The integration requires access to the Reflow source repository. It is not a self-service public Action install. With source access, start from these files at the same reviewed commit:

• Native setup action (.github/actions/reflow-setup/action.yml): installer, connection and private profile setup.
• Native run action (.github/actions/reflow-run/action.yml): plan/apply lifecycle and result receipt.
• Complete reference workflow (.github/workflows/pitminder-reflow.yml): separate execution and trusted publisher jobs, export, artifact upload and cleanup.
• Trusted comment publisher (gh-action/src/cliReportMain.ts) and report exporter (gh-action/scripts/cli-review-export.mjs).

These native reporting actions and the PitMinder recipe still use repository file selection; they do not accept a collection input. For an activated test collection, use gh-action/action.yml as described above, or run the installed CLI directly with target --collection. The collection Action does not supply the native recipe’s PR comment exporter. Keep the controller’s run and artifact links for review; do not rerun a test through another execution path for an export.

Use the full reviewed commit SHA when wiring your workflow. Adapt the reference workflow’s application-specific fixture and flow paths; copying its PitMinder setup does not configure your application. If you do not have source access, use the local CLI and the MCP review export with your existing authorized PR delivery process.

Open the visual report

The comment’s Download visual report link points to a private GitHub Actions artifact. Download and extract it, then open index.html. The report includes local image files, so its selected evidence remains readable after the disposable execution environment is removed.

Repository access is required. The comment shows artifact expiry; the current integration retains the report for 14 days. Changed or new captures lead the summary and completed flows are collapsed. Captures without an approved baseline are shown as new captures. Failures and missing evidence remain visible.

This hosted path links the report; it does not embed screenshots or GIFs inline in the PR comment.

Add knowledge and review notes

Your authoring agent can separately prepare a base/candidate comparison with knowledge patches, changed evidence and review notes. A fresh agent can inspect originals and add an independent assessment. Follow the MCP preparation workflow.

prepare_comment and export_comment prepare Markdown and selected media. Export saves files; an authorized delivery step publishes them. The existing comparison delivery mode takes that prepared selection. Ordinary CLI reporting does not automatically generate a knowledge comparison.

Branch rules determine which GitHub checks block merging. PR review does not automatically approve screenshot baselines; baseline approval is a separate decision.