Staged Mode

Staged mode lets you run a workflow and see what 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:

---
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 appears in every heading to make previews 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 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`	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 to start with staged mode and disable it once you’re satisfied with the output:

Enable staged: true and trigger the workflow on a real event.
Open the Actions run and review the preview in the step summary.
Adjust the workflow prompt or configuration based on the preview.
Repeat until the output looks correct.
Remove staged: true (or set it to false) to start creating real GitHub resources.

Safe Outputs — All built-in safe output types and their configuration
Custom Safe Outputs — Adding custom jobs with staged mode support
Frontmatter (Full) — Complete configuration reference
Threat Detection — Security scanning for safe output content