GitHub Agentic Workflows: Review Safe Outputs Before Enabling Writes

Before enabling an AI workflow to write to a repository, identify which component holds the write authority, which outputs are only previews, and what happens when detection cannot produce a verdict. GitHub Agentic Workflows separates these decisions; a successful run or a read-only agent job does not answer all three.

GitHub announced Agentic Workflows general availability on 28 October 2026. This guide reviews its current documentation rather than reporting a tested deployment. The reference pages are moving documentation, not a version-pinned behavioral guarantee. Record your adopted compiler version and inspect its generated workflow before applying this checklist. Announcement

What does the read-only default cover?

Agentic Workflows uses Markdown instructions with YAML frontmatter. The compiler produces a .lock.yml Actions workflow: configuration is compiled into that file, while the Markdown body is loaded at runtime. The generated agent job is read-only by default; the recommended write path uses safe-outputs. Direct writes and custom jobs remain configurable. Overview

This generated .lock.yml is different from the actions.lock dependency-resolution file discussed in our GitHub Actions lockfile review guide. Do not use the similar names as evidence that prompts, dependencies, and runtime behavior are all frozen.

In the documented safe-output path, the agent proposes changes as buffered artifacts. Separate jobs perform scoped writes after processing those proposals. This separates the agent’s direct repository permissions from the authority that applies its output. Security architecture

Figure 1. Original conceptual map, not a complete execution trace or safety certification. Warn mode can allow annotated reviewable outputs.

Our practical interpretation: permission separation limits a direct write path, but a permitted comment can still be misleading and a permitted patch can still be wrong. Review the proposed content as well as the permission boundary.

Staged mode previews built-in writes, not every side effect

Global safe-outputs.staged: true makes built-in outputs previews in the Actions step summary instead of applying their writes. With global staging unset or false, a type-level staged: true previews only that type; other types can still execute. A type-level false does not override global true. Staged-mode reference

For a hypothetical issue-triage pilot, start by previewing the proposed response. Inspect whether it answers the issue, reveals inappropriate information, or invents a diagnosis. This is an editorial recommendation, not a measured accuracy result.

Staging is not a whole-workflow sandbox. Custom jobs, scripts, external MCP servers, extra credentials, persistence, and diagnostic exports need separate controls. Custom safe-output jobs must implement the staging signal themselves; they are not automatically skipped. Staging boundaries

Before treating a run as preview-only, inventory every executable component and credential. A preview of the final comment says nothing by itself about another script’s earlier effects. Keep the pilot free of unnecessary custom authority rather than assuming one flag neutralizes it.

Decide how detector failures affect publication

The current threat-detection configuration table documents continue-on-error: true as the default warn mode, consistent with the architecture page. For detected threats or detector failures, reviewable outputs may be annotated, branch pushes become review pull requests, and non-reviewable operations are aborted. Setting false selects strict behavior that fails detection and prevents safe outputs on those outcomes. Detection reference

A detector failure is no verdict, not a clean bill of health. These sources also contain simplified diagrams and shorter wording that can suggest a universal approve-or-block gate. Do not infer default behavior from those illustrations. We have not resolved documentation differences through execution. Confirm the policy of your adopted version before enabling writes. Detection reference

Our recommendation for an initial pilot: choose deliberately whether an uncertain result should stop output, and record that decision. Even strict detection is not proof that an accepted patch or comment is correct; retain the normal review and test requirements for changes.

A release-review worksheet

Use this worksheet for one narrowly scoped workflow before expanding its responsibility. It is our review framework, not an official certification or an exhaustive security audit.

Decision	Evidence to retain	Reason to hold the rollout
Intended result	A sample proposed comment or patch and its reader task	The output is plausible but unsupported.
Write path	Generated jobs, their permissions, and credential inventory	A custom path has unexplained authority.
Preview scope	Global and per-type staging settings; custom-job behavior	Someone assumes all effects were disabled.
Detection policy	Actual configured mode and handling of an unavailable verdict	Failure is being treated as success.
Change acceptance	Existing tests, review ownership, and rollback procedure	AI output would bypass ordinary acceptance criteria.

GitHub’s architecture explicitly treats setup, post-processing, custom jobs, and detection steps as trusted executable code rather than automatically confining them to the agent sandbox. A read-only GITHUB_TOKEN does not remove other credentials or host access. Architecture

The useful starting point is a small, observable task with limited consequences. Expand only when you can explain every route from input to external effect. The product’s safety mechanisms are inputs to that explanation, not substitutes for it.