Staged Mode

Staged mode lets you run a workflow and preview the built-in safe outputs it would create — issues, comments, pull requests, and more — without applying those writes. Staged built-in operations are replaced with a detailed preview in the GitHub Actions step summary.

Use it to review proposed safe outputs before enabling their production writes. Staging is not a sandbox: custom jobs, scripts, external MCP servers, custom credentials, memory/cache persistence, and diagnostic exports require separate controls. Compile dry-run disables additional compiler-managed mutations but does not sandbox custom code.

Enabling Staged Mode

Add staged: true to the safe-outputs: block in your workflow frontmatter:

---
on: issues

safe-outputs:
  staged: true
  create-issue:
    title-prefix: "[ai] "
    labels: [automation]
---

# Issue Analyzer

Analyze the issue and suggest follow-up tasks.

The workflow runs fully, but no issues are created; the run summary shows a preview instead.

Scoping Staged Mode per Output Type

Use staged: true on a specific type to preview only that output type while letting others execute normally:

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

A built-in output is staged when either the global setting or its type-level setting is true. With global staging false or unset, type-level staging lets you preview one output type while keeping others active. Type-level staged: false cannot disable global staging, including staging forced by compile --staged or --dry-run.

What the Preview Looks Like

The step summary contains a preview for each output type, with every heading marked :

##  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 populated field.

Supported Output Types

All built-in safe output types support staged mode:

Output type	What the preview shows
create-issue	Title, body, labels, assignees
update-issue	Target issue, updated fields
close-issue	Target issue, closing comment
add-comment	Target issue/PR/discussion, comment body
add-labels	Target item, labels to add
remove-labels	Target item, labels to remove
create-discussion	Title, body, category
update-discussion	Target discussion, updated fields
close-discussion	Target discussion, closing comment
create-pull-request	Title, body, branch, diff
update-pull-request	Target PR, updated fields
close-pull-request	Target PR
create-pull-request-review-comment	File, line, comment body
push-to-pull-request-branch	Branch, patch summary
create-project	Project title, description
update-project	Target project, project items and fields to update
create-project-status-update	Status, body
update-release	Target release, updated body
upload-asset	File names and sizes
dispatch-workflow	Target workflow, inputs
assign-to-agent	Target issue/PR
assign-to-user	Target item, user
create-agent-session	Session details

Staged Mode for Custom Safe Output Jobs

Custom safe output jobs receive GH_AW_SAFE_OUTPUTS_STAGED=true when staged mode is active. They are not automatically skipped: their code must check it to show a preview instead of the real operation, and their credentials and external effects still require review.

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 for a complete example.

Customizing Preview Messages

Override the default preview heading and description using the messages: block:

---
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

Enable staged: true, trigger the workflow on a real event, review the preview, and adjust the prompt or configuration until the output looks correct. Then disable staged mode.

Tip

Re-enable staging for a single output type when introducing a new safe output.

Learn More

See Safe Outputs, Custom Safe Outputs, Frontmatter (Full), and Threat Detection.