Safe-Outputs Samples

Experimental — hidden

The samples: field and the gh aw compile --use-samples flag are an internal, undocumented testing feature. The shape of samples: entries, the set of recognized sidecar fields, and the replay driver behavior may change at any time without notice. The --use-samples flag is hidden from gh aw compile --help on purpose.

samples: is an optional per-handler list under any safe-output block that declares a fixed set of payloads the workflow should “produce” instead of running the agent. When gh aw compile is invoked with the hidden --use-samples flag, the compiled workflow’s agentic Execute coding agent step is replaced with a deterministic driver that feeds each sample to the safe-outputs MCP server via real tools/call JSON-RPC. This lets end-to-end tests exercise safe-output handlers, the safe-outputs MCP server, and the post-processing jobs without any non-determinism from a real LLM.

When to use it

Use samples replay only to make CI for gh-aw itself deterministic — for example, smoke-testing a new safe-output handler, validating MCP routing changes, or exercising the post-processing jobs that consume outputs.jsonl. Workflows shipped to users should never rely on samples:; remove the field before publishing.

Declaring samples

Add a samples: list to any enabled safe-output handler. Each entry is a JSON object whose keys must conform to the corresponding MCP tool’s inputSchema (the same schema the agent’s tools/call payload would have to satisfy).

---
on:
  workflow_dispatch:
permissions: read-all
engine:
  id: claude
safe-outputs:
  create-issue:
    samples:
      - title: "Sample issue from gh-aw samples"
        body: "Body emitted by the deterministic replay driver."
        labels: [automated, sample]
---

Trivial workflow whose only job is to be compiled with --use-samples.

Compile with the hidden flag:

gh aw compile --use-samples .github/workflows/my-workflow.md

Alternatively, a single workflow can opt itself in with the features.samples: true flag, which has exactly the same effect as --use-samples but applies only to that workflow. Use it for workflows that are designed around samples: (such as this repository’s own smoke tests) so a plain gh aw compile — and therefore make recompile — keeps producing the samples-mode lock file:

features:
  samples: true

The generated .lock.yml replaces the agentic step with:

- name: Replay safe-outputs samples (deterministic)
  id: agentic_execution
  env:
    GH_AW_SAMPLES: |
      [{"tool":"create_issue","arguments":{...}}]
  run: |
    node "${{ runner.temp }}/gh-aw/actions/apply_samples.cjs"

Sidecar fields

Some samples carry data that is not part of the MCP tool’s tools/call arguments but is instead pre-staged on disk by the replay driver. These “sidecar” fields are stripped from the sample before schema validation and consumed by the driver: