docs: add dedicated staged mode documentation page for safe outputs by Copilot · Pull Request #20269 · github/gh-aw

Copilot · 2026-03-09T22:22:13Z

Staged mode is a compelling "try before you buy" feature for safe outputs — run the workflow, see exactly what it would create in the Actions step summary, no side effects. It was only mentioned in the spec and a terse glossary entry.

Changes

New page reference/staged-mode.md — covers enabling globally vs. per output type, the 🎭 preview format, a full per-type support table with deep links to each safe output's reference section, custom job support via GH_AW_SAFE_OUTPUTS_STAGED, custom staged-title/staged-description message templates, and a recommended staged→review→enable adoption pattern
safe-outputs.md — new "Staged Mode" section with quick-start examples (global and per-type) and link to the dedicated page; staged mode added to Related Documentation
glossary.md — glossary entry now links to the new page
astro.config.mjs — "Safe Outputs (Staged Mode)" added to Reference sidebar adjacent to other safe output pages

Example

safe-outputs:
  staged: false
  create-pull-request:
    staged: true   # preview PRs, execute comments normally
  add-comment:

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/graphql
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw GO111MODULE x_amd64/vet git rev-�� --show-toplevel x_amd64/vet /usr/bin/git -json GO111MODULE 64/pkg/tool/linu--show-toplevel git (http block)
https://api.github.com/repos/actions/ai-inference/git/ref/tags/v1
- Triggering command: /usr/bin/gh gh api /repos/actions/ai-inference/git/ref/tags/v1 --jq .object.sha /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet /opt/hostedtoolcgit sh 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -uns�� -unreachable=false resolved$ /usr/bin/git -json GO111MODULE x_amd64/vet git (http block)
https://api.github.com/repos/actions/checkout/git/ref/tags/v3
- Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq .object.sha runs/20260309-223219-29727/test-1448452878/.github/workflows /tmp/go-build2538829325/b054/vet.cfg ache/node/24.14.0/x64/bin/node -json GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet t-33�� sistency_GoAndJavaScript3304800080/001/test-simple-frontmatter.md /tmp/go-build2538829325/b242/vet.cfg /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -json GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/actions/checkout/git/ref/tags/v5
- Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq .object.sha -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
- Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq .object.sha --show-toplevel x_amd64/asm /usr/bin/git rt GO111MODULE x_amd64/vet git conf�� user.name Test User /usr/bin/git -json GO111MODULE x_amd64/vet git (http block)
https://api.github.com/repos/actions/checkout/git/ref/tags/v6
- Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha /tmp/gh-aw-test-runs/20260309-223219-29727/test-3745043716/.github/workflows (http block)
- Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha k/gh-aw/gh-aw/pkg/styles/theme.go k/gh-aw/gh-aw/pkg/styles/theme_test.go /opt/hostedtoolcache/node/24.14.0/x64/bin/node npx prettier --cgit GOPROXY 64/bin/go node /tmp�� /tmp/TestHashConsistency_GoAndJavaScript3304800080/001/test-empty-frontmatter.md node /usr/bin/git --check scripts/**/*.js 64/bin/go git (http block)
https://api.github.com/repos/actions/github-script/git/ref/tags/v8
- Triggering command: /usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha abht/izPa48e1cGnGOSUMDB GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE 5696210/b406/imp-buildtags /hom�� k/gh-aw/gh-aw/pk-errorsas k/gh-aw/gh-aw/pk-ifaceassert 64/bin/go **/*.json --ignore-path ../../../.pretti-unreachable=false /opt/hostedtoolc/tmp/go-build2538829325/b309/vet.cfg (http block)
- Triggering command: /usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha "prettier" --check '**/*.cjs' '*GOINSECURE GOPROXY 64/bin/go GOSUMDB GOWORK 64/bin/go git cat-�� blob a17ccd702bb947802f14e9f6243ae1faGOMOD 64/bin/go "prettier" --wri/opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet git 64/bin/go go (http block)
- Triggering command: /usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha k/gh-aw/gh-aw/cmd/gh-aw/main.go GOPROXY 64/bin/go GOSUMDB GOWORK 64/bin/go /opt/hostedtoolc-buildtags -o /tmp/go-build349-errorsas -trimpath 64/bin/go -p main -lang=go1.25 go (http block)
https://api.github.com/repos/actions/setup-go/git/ref/tags/v4
- Triggering command: /usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq .object.sha --show-toplevel -tests /tmp/go-build2538829325/b409/parser.test npx prettier --cgit GOPROXY 64/bin/go /tmp/go-build2538829325/b409/parser.test -tes�� -test.paniconexit0 -test.v=true /usr/bin/gh -test.timeout=10git -test.run=^Test -test.short=true--show-toplevel gh (http block)
https://api.github.com/repos/actions/setup-node/git/ref/tags/v4
- Triggering command: /usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq .object.sha /tmp/gh-aw-test-runs/20260309-223219-29727/test-3745043716/.github/workflows config /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet remote.origin.urgit GOPROXY 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -ato�� -bool -buildtags (http block)
https://api.github.com/repos/actions/upload-artifact/git/ref/tags/v4
- Triggering command: /usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq .object.sha -json GO111MODULE epo.git GOINSECURE GOMOD GOMODCACHE /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linutest@example.com -uns�� -unreachable=false /tmp/go-build2538829325/b089/vet.cfg 8829325/b310/vet.cfg GOSUMDB GOWORK 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/1/artifacts
- Triggering command: /usr/bin/gh gh run download 1 --dir test-logs/run-1 GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/12345/artifacts
- Triggering command: /usr/bin/gh gh run download 12345 --dir test-logs/run-12345 GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet env -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linuremote.origin.url (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/12346/artifacts
- Triggering command: /usr/bin/gh gh run download 12346 --dir test-logs/run-12346 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet estl�� -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/2/artifacts
- Triggering command: /usr/bin/gh gh run download 2 --dir test-logs/run-2 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet estl�� -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/3/artifacts
- Triggering command: /usr/bin/gh gh run download 3 --dir test-logs/run-3 GO111MODULE x_amd64/link GOINSECURE GOMOD GOMODCACHE x_amd64/link env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE f6/UQ_LKbCoOr4J2KxFnQDi/Aq_bifo_--jq (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/4/artifacts
- Triggering command: /usr/bin/gh gh run download 4 --dir test-logs/run-4 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet estl�� -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/actions/runs/5/artifacts
- Triggering command: /usr/bin/gh gh run download 5 --dir test-logs/run-5 GO111MODULE 64/pkg/tool/linu-nolocalimports GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linu/tmp/go-build2538829325/b422/_testmain.go estl�� g_.a GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/actions/workflows
- Triggering command: /usr/bin/gh gh workflow list --json name,state,path -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE npx pret�� --check scripts/**/*.js 64/bin/go .prettierignore GOWORK 64/bin/go go (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.0.0
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.0.0 --jq .object.sha -json GO111MODULE datedAt,event,headBranch,headSha,displayTitle GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.2.3
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.2.3 --jq .object.sha "prettier" --check 'scripts/**/*GOINSECURE node 64/bin/go tierignore --write 64/bin/go go env -json GO111MODULE x_amd64/cgo GOINSECURE GOMOD GOMODCACHE x_amd64/cgo (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/v2.0.0
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha "prettier" --check 'scripts/**/*GOINSECURE node 64/bin/go tierignore --write 64/bin/go go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet (http block)
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha --check scripts/**/*.js 64/bin/go /golden.go (http block)
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha /opt/hostedtoolc-json sh 64/bin/go -d git 64/bin/go go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/v3.0.0
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v3.0.0 --jq .object.sha --check scripts/**/*.js 64/bin/go .prettierignore git 64/bin/go go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet (http block)
https://api.github.com/repos/nonexistent/action/git/ref/tags/v999.999.999
- Triggering command: /usr/bin/gh gh api /repos/nonexistent/action/git/ref/tags/v999.999.999 --jq .object.sha -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env 2504885164/.github/workflows .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/nonexistent/repo/actions/runs/12345
- Triggering command: /usr/bin/gh gh run view 12345 --repo nonexistent/repo --json status,conclusion GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
https://api.github.com/repos/owner/repo/actions/workflows
- Triggering command: /usr/bin/gh gh workflow list --json name,state,path --repo owner/repo 64/bin/go GOSUMDB GOWORK 64/bin/go sh -c "prettier" --che-errorsas sh 64/bin/go npx prettier --w/opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet on 64/bin/go go (http block)
- Triggering command: /usr/bin/gh gh workflow list --json name,state,path --repo owner/repo 64/bin/go GOSUMDB GOWORK 64/bin/go sh -c "prettier" --che-c=4 sh 64/bin/go npx prettier --w/opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet on 64/bin/go go (http block)
https://api.github.com/repos/owner/repo/contents/file.md
- Triggering command: /tmp/go-build2538829325/b383/cli.test /tmp/go-build2538829325/b383/cli.test -test.testlogfile=/tmp/go-build2538829325/b383/testlog.txt -test.paniconexit0 -test.v=true -test.parallel=4 -test.timeout=10m0s -test.run=^Test -test.short=true GOINSECURE GOMOD GOMODCACHE 5696210/b390/imp/tmp/go-build2538829325/b145/vet.cfg -c k/gh-aw/gh-aw/pkg/constants/consGOINSECURE k/gh-aw/gh-aw/pkg/constants/consGOMOD 64/bin/go GOSUMDB GOWORK 64/bin/go /opt/hostedtoolc-buildtags (http block)
https://api.github.com/repos/test-owner/test-repo/actions/secrets
- Triggering command: /usr/bin/gh gh api /repos/test-owner/test-repo/actions/secrets --jq .secrets[].name Ffi0/lYwbufauQd9GOSUMDB GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE 5696210/b402/imp-buildtags /hom�� k/gh-aw/gh-aw/pk-errorsas k/gh-aw/gh-aw/pk-ifaceassert 64/bin/go **/*.json --ignore-path ../../../.pretti-bool /opt/hostedtoolc-buildtags (http block)
telemetry.astro.build
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
- Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build go env -o public/slides/index.html GO111MODULE 64/bin/go s/gh-aw-theme.css -o public/slides/index.html && mkdir -p public/slides && cp slides/github-age GOMOD GOMODCACHE go env -json GO111MODULE es/.bin/sh GOINSECURE GOMOD GOMODCACHE go (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot

Pull request overview

Adds a dedicated documentation page for “Staged Mode” to make safe output previews easier to discover and adopt.

Changes:

Introduces a new reference/staged-mode.md page covering configuration, preview format, and custom job support.
Adds a “Staged Mode” quick-start section and related doc link to safe-outputs.md.
Updates navigation/discoverability via the glossary link and Reference sidebar entry.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/src/content/docs/reference/staged-mode.md	New reference page documenting staged mode usage, previews, and customization.
docs/src/content/docs/reference/safe-outputs.md	Adds staged mode section + related documentation link pointing to the new page.
docs/src/content/docs/reference/glossary.md	Updates staged mode glossary entry to link to the new staged mode page.
docs/astro.config.mjs	Adds “Safe Outputs (Staged Mode)” to the Reference sidebar.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-09T22:42:40Z

docs/src/content/docs/reference/safe-outputs.md


+## Staged Mode
+
+Staged mode lets you preview what safe outputs a workflow would create without actually creating anything. Every write operation is skipped; instead, a 🎭-labelled preview appears in the GitHub Actions step summary.


The text uses UK spelling "🎭-labelled"; elsewhere in these docs the standard spelling is "labeled" (e.g., GitHub event types like labeled). Consider changing this to "🎭-labeled" for consistency.

Suggested change

Staged mode lets you preview what safe outputs a workflow would create without actually creating anything. Every write operation is skipped; instead, a 🎭-labelled preview appears in the GitHub Actions step summary.

Staged mode lets you preview what safe outputs a workflow would create without actually creating anything. Every write operation is skipped; instead, a 🎭-labeled preview appears in the GitHub Actions step summary.

Copilot · 2026-03-09T22:42:40Z

docs/src/content/docs/reference/safe-outputs.md

+  create-pull-request:
+    staged: true   # preview only
+  add-comment:     # executes normally


This example is introduced as leaving the global safe-outputs.staged setting at false, but the snippet doesn’t show staged: false at the top level. Either include staged: false in the example for clarity, or adjust the wording to reflect that staged defaults to false when omitted.

Suggested change

create-pull-request:

staged: true # preview only

add-comment: # executes normally

staged: false # global default

create-pull-request:

staged: true # preview only

add-comment: # executes normally

Initial plan

a17ccd7

Copilot AI assigned Copilot and pelikhan Mar 9, 2026

Copilot started work on behalf of pelikhan March 9, 2026 22:22 View session

Copilot AI linked an issue Mar 9, 2026 that may be closed by this pull request

Staged mode support needs better docs #20241

Closed

docs: add dedicated staged mode documentation page (#3434)

f3cfd38

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add documentation for staged mode support in safe outputs~~ docs: add dedicated staged mode documentation page for safe outputs Mar 9, 2026

Copilot finished work on behalf of pelikhan March 9, 2026 22:35

pelikhan approved these changes Mar 9, 2026

View reviewed changes

pelikhan marked this pull request as ready for review March 9, 2026 22:39

Copilot AI review requested due to automatic review settings March 9, 2026 22:39

Copilot started reviewing on behalf of pelikhan March 9, 2026 22:40 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

pelikhan merged commit a550a7e into main Mar 9, 2026
64 checks passed

pelikhan deleted the copilot/add-staged-mode-documentation branch March 9, 2026 22:43

This was referenced Mar 10, 2026

Smoke Test: Claude - 22881817319 #20286

Closed

Smoke Test: Copilot - 22882411590 #20291

Closed

[docs] Update documentation for features from 2026-03-10 #20306

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add dedicated staged mode documentation page for safe outputs#20269

docs: add dedicated staged mode documentation page for safe outputs#20269
pelikhan merged 2 commits intomainfrom
copilot/add-staged-mode-documentation

Copilot AI commented Mar 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Staged Mode

		Staged mode lets you preview what safe outputs a workflow would create without actually creating anything. Every write operation is skipped; instead, a 🎭-labelled preview appears in the GitHub Actions step summary.

Conversation

Copilot AI commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 9, 2026 •

edited

Loading