Staged Mode

Staged mode lets you run a workflow and preview the safe outputs it would create — issues, comments, pull requests, and more — without making any changes. Every write operation is skipped and replaced with a detailed preview in the GitHub Actions step summary.

Use it to validate a new workflow before it has any real effect, or to share what a workflow would do before enabling it in production.

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.

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:

---
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 marks every heading so previews are easy to spot:

##  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 — title, body, labels, assignees, and similar metadata — so you can review the full output before enabling it.

Supported Output Types

Staged mode is supported by all built-in safe output types:

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

Custom safe output jobs 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:

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

A common adoption pattern is:

Enable staged: true and trigger the workflow on a real event.
Review the preview in the Actions run summary.
Adjust the prompt or configuration.
Repeat until the output looks correct.
Disable staged mode to start creating real GitHub resources.

See Safe Outputs for built-in output types, Custom Safe Outputs for custom jobs with staged mode support, Frontmatter (Full) for the full configuration reference, and Threat Detection for security scanning of safe output content.