From a17ccd702bb947802f14e9f6243ae1fa9636ead7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 22:22:12 +0000 Subject: [PATCH 1/2] Initial plan From f3cfd389a302fc70ce4ae7b77ea03f55f7e17951 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 22:35:06 +0000 Subject: [PATCH 2/2] docs: add dedicated staged mode documentation page (#3434) Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/astro.config.mjs | 1 + docs/src/content/docs/reference/glossary.md | 2 +- .../content/docs/reference/safe-outputs.md | 28 +++ .../src/content/docs/reference/staged-mode.md | 166 ++++++++++++++++++ 4 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 docs/src/content/docs/reference/staged-mode.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index a61a8c6f9fc..b22f23eef08 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -320,6 +320,7 @@ export default defineConfig({ { label: 'Safe Outputs', link: '/reference/safe-outputs/' }, { label: 'Safe Outputs (Pull Requests)', link: '/reference/safe-outputs-pull-requests/' }, { label: 'Safe Outputs (Spec)', link: '/reference/safe-outputs-specification/' }, + { label: 'Safe Outputs (Staged Mode)', link: '/reference/staged-mode/' }, { label: 'Sandbox', link: '/reference/sandbox/' }, { label: 'Schedule Syntax', link: '/reference/schedule-syntax/' }, { label: 'Templating', link: '/reference/templating/' }, diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md index 7db1f3c33b4..42c8e698ae0 100644 --- a/docs/src/content/docs/reference/glossary.md +++ b/docs/src/content/docs/reference/glossary.md @@ -102,7 +102,7 @@ An optional field on safe output tool calls indicating the confidentiality level ### Staged Mode -A preview mode where workflows simulate actions without making changes. The AI generates output showing what would happen, but no GitHub API write operations are performed. Use for testing before production runs. +A preview mode where workflows simulate actions without making changes. The AI generates output showing what would happen, but no GitHub API write operations are performed. Use for testing before production runs. See [Staged Mode](/gh-aw/reference/staged-mode/) for details. ### Integrity diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index bd394a410e1..b46db4eb624 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -1349,8 +1349,36 @@ safe-outputs: **Variables**: `{workflow_name}`, `{run_url}`, `{triggering_number}`, `{workflow_source}`, `{workflow_source_url}`, `{event_type}`, `{status}`, `{operation}` +## 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. + +Enable it globally by adding `staged: true` to the `safe-outputs:` block: + +```yaml wrap +safe-outputs: + staged: true + create-issue: + title-prefix: "[ai] " + labels: [automation] +``` + +You can also scope staged mode to a specific output type by adding `staged: true` directly to that type while leaving the global setting at `false`: + +```yaml wrap +safe-outputs: + create-pull-request: + staged: true # preview only + add-comment: # executes normally +``` + +To disable staged mode and start creating real resources, remove the `staged: true` setting or set it to `false`. + +See [Staged Mode](/gh-aw/reference/staged-mode/) for the full guide, including the preview message format, per-type support table, custom message templates, and how to implement staged mode in [custom safe output jobs](/gh-aw/reference/custom-safe-outputs/#staged-mode-support). + ## Related Documentation +- [Staged Mode](/gh-aw/reference/staged-mode/) - Preview safe output operations without making changes - [Threat Detection Guide](/gh-aw/reference/threat-detection/) - Complete threat detection documentation and examples - [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options for workflows - [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory layout and organization diff --git a/docs/src/content/docs/reference/staged-mode.md b/docs/src/content/docs/reference/staged-mode.md new file mode 100644 index 00000000000..75100758525 --- /dev/null +++ b/docs/src/content/docs/reference/staged-mode.md @@ -0,0 +1,166 @@ +--- +title: Staged Mode +description: Preview safe output operations without making any changes, so you can see exactly what a workflow would do before it acts. +sidebar: + order: 820 +--- + +Staged mode lets you run a workflow and see what [safe outputs](/gh-aw/reference/safe-outputs/) it would create — issues, comments, pull requests, and more — without actually creating anything. Every write operation is skipped; instead, a detailed preview appears in the GitHub Actions step summary with a 🎭 indicator. + +This is useful when you're adopting a new workflow and want to verify its behavior before it has any real effect, or when you want to share what a workflow *would* do with colleagues before enabling it in production. + +## Enabling Staged Mode + +Add `staged: true` to the `safe-outputs:` block in your workflow frontmatter: + +```aw wrap +--- +on: issues +safe-outputs: + staged: true + create-issue: + title-prefix: "[ai] " + labels: [automation] +--- + +# Issue Analyzer + +Analyze the issue and suggest follow-up tasks. +``` + +With this configuration the workflow runs fully — the AI completes its analysis — but no issues are created. Instead, the Actions run summary shows a preview of what would have been created. + +## Scoping Staged Mode per Output Type + +Use `staged: true` on a specific type to preview only that output type while letting others execute normally: + +```aw wrap +--- +safe-outputs: + staged: false # default: execute normally + create-pull-request: + staged: true # PRs: preview only + add-comment: # comments: execute normally +--- +``` + +A type-level `staged` setting overrides the global one, so you can pilot one risky output type while keeping other outputs fully active. + +## What the Preview Looks Like + +When staged mode is active the step summary contains a structured preview for each output type. The 🎭 emoji appears in every heading to make previews easy to spot: + +```markdown +## 🎭 Staged Mode: Issue Creation Preview + +The following 2 issue(s) would be performed if staged mode was disabled: + +### Operation 1: Add caching layer to database queries + +**Type**: create-issue +**Title**: Add caching layer to database queries +**Body**: +Performance profiling shows repeated queries to the users table … + +**Additional Fields**: +- Labels: performance, database +- Assignees: octocat + +### Operation 2: Update connection pool settings + +… + +--- +**Preview Summary**: 2 operations previewed. No GitHub resources were created. +``` + +The preview includes every field the AI populated — title, body, labels, assignees — so you can evaluate the full output before enabling. + +## Supported Output Types + +Staged mode is supported by all built-in safe output types: + +| Output type | What the preview shows | +|---|---| +| [`create-issue`](/gh-aw/reference/safe-outputs/#issue-creation-create-issue) | Title, body, labels, assignees | +| [`update-issue`](/gh-aw/reference/safe-outputs/#issue-updates-update-issue) | Target issue, updated fields | +| [`close-issue`](/gh-aw/reference/safe-outputs/#close-issue-close-issue) | Target issue, closing comment | +| [`add-comment`](/gh-aw/reference/safe-outputs/#comment-creation-add-comment) | Target issue/PR/discussion, comment body | +| [`add-labels`](/gh-aw/reference/safe-outputs/#add-labels-add-labels) | Target item, labels to add | +| [`remove-labels`](/gh-aw/reference/safe-outputs/#remove-labels-remove-labels) | Target item, labels to remove | +| [`create-discussion`](/gh-aw/reference/safe-outputs/#discussion-creation-create-discussion) | Title, body, category | +| [`update-discussion`](/gh-aw/reference/safe-outputs/#discussion-updates-update-discussion) | Target discussion, updated fields | +| [`close-discussion`](/gh-aw/reference/safe-outputs/#close-discussion-close-discussion) | Target discussion, closing comment | +| [`create-pull-request`](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-creation-create-pull-request) | Title, body, branch, diff | +| [`update-pull-request`](/gh-aw/reference/safe-outputs/#pull-request-updates-update-pull-request) | Target PR, updated fields | +| [`close-pull-request`](/gh-aw/reference/safe-outputs/#close-pull-request-close-pull-request) | Target PR | +| [`create-pull-request-review-comment`](/gh-aw/reference/safe-outputs/#pr-review-comments-create-pull-request-review-comment) | File, line, comment body | +| [`push-to-pull-request-branch`](/gh-aw/reference/safe-outputs-pull-requests/#push-to-pr-branch-push-to-pull-request-branch) | Branch, patch summary | +| [`create-project`](/gh-aw/reference/safe-outputs/#project-creation-create-project) | Project title, description | +| [`update-project`](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) | Target project, project items and fields to update | +| [`create-project-status-update`](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) | Status, body | +| [`update-release`](/gh-aw/reference/safe-outputs/#release-updates-update-release) | Target release, updated body | +| [`upload-asset`](/gh-aw/reference/safe-outputs/#asset-uploads-upload-asset) | File names and sizes | +| [`dispatch-workflow`](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) | Target workflow, inputs | +| [`assign-to-agent`](/gh-aw/reference/safe-outputs/#assign-to-agent-assign-to-agent) | Target issue/PR | +| [`assign-to-user`](/gh-aw/reference/safe-outputs/#assign-to-user-assign-to-user) | Target item, user | +| [`create-agent-session`](/gh-aw/reference/safe-outputs/#agent-session-creation-create-agent-session) | Session details | + +[Custom safe output jobs](/gh-aw/reference/custom-safe-outputs/) receive the `GH_AW_SAFE_OUTPUTS_STAGED` environment variable set to `"true"` when staged mode is active, allowing you to implement your own preview behavior. + +## Staged Mode for Custom Safe Output Jobs + +Custom jobs check `GH_AW_SAFE_OUTPUTS_STAGED` to skip the real operation and display a preview instead: + +```javascript +if (process.env.GH_AW_SAFE_OUTPUTS_STAGED === 'true') { + core.info('🎭 Staged mode: would send Slack notification'); + await core.summary + .addHeading('🎭 Staged Mode: Slack Notification Preview', 2) + .addRaw(`**Would send**: ${process.env.MESSAGE}`) + .write(); + return; +} + +// Production path — actually send the notification +await sendSlackMessage(process.env.MESSAGE); +``` + +See [Custom Safe Outputs — Staged Mode Support](/gh-aw/reference/custom-safe-outputs/#staged-mode-support) for a complete example. + +## Customizing Preview Messages + +Override the default preview heading and description using the `messages:` block: + +```aw wrap +--- +safe-outputs: + staged: true + messages: + staged-title: "🎭 Preview: {operation}" + staged-description: "The following {operation} would occur if staged mode was disabled:" + create-issue: +--- +``` + +The `{operation}` placeholder is replaced with the safe output operation name (for example, `issue creation`). + +## Recommended Workflow + +A common adoption pattern is to start with staged mode and disable it once you're satisfied with the output: + +1. Enable `staged: true` and trigger the workflow on a real event. +2. Open the Actions run and review the 🎭 preview in the step summary. +3. Adjust the workflow prompt or configuration based on the preview. +4. Repeat until the output looks correct. +5. Remove `staged: true` (or set it to `false`) to start creating real GitHub resources. + +> [!TIP] +> Keep staged mode enabled when iterating on prompt changes, and only remove it when the workflow is stable. You can always re-enable it for a single type if you add a new safe output. + +## Related Documentation + +- [Safe Outputs](/gh-aw/reference/safe-outputs/) — All built-in safe output types and their configuration +- [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) — Adding custom jobs with staged mode support +- [Frontmatter (Full)](/gh-aw/reference/frontmatter-full/) — Complete configuration reference +- [Threat Detection](/gh-aw/reference/threat-detection/) — Security scanning for safe output content