Safe Update Specification | GitHub Agentic Workflows
Skip to main content Safe Update Specification Version : 1.0.0 Status : Working Draft Publication Date : 2026-07-11 Editor : GitHub Agentic Workflows Team This Version : safe-update-specification Latest Published Version : This document Abstract Section titled “Abstract” This specification defines safe update behavior in GitHub Agentic Workflows compilation. It standardizes when safe update enforcement is active, how baseline manifests are loaded and trusted, which secret/action/redirect/event changes require review, how warnings are surfaced, and how approval and strict-mode settings affect enforcement.
Status of This Document Section titled “Status of This Document” This is a working draft and may change. It describes behavior implemented in pkg/workflow/ and exercised by pkg/workflow/*safe_update* and pkg/cli/compile_safe_update_integration_test.go . Table of Contents Section titled “Table of Contents” Introduction Conformance Safe Update Activation Model Baseline Manifest Resolution and Trust Violation Detection Rules Compiler Output and Approval Flow Manifest Format Requirements Compliance Testing References Change Log 1.
Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” This document defines normative requirements for safe update enforcement during workflow compilation so that newly introduced security-sensitive changes are surfaced for review. 1.2 Scope Section titled “1.2 Scope” This specification covers: safe update activation and disablement behavior baseline manifest lookup precedence and trust guarantees restricted secret and action change detection redirect and event-trigger escalation detection warning/prompt emission and approval workflow gh-aw-manifest content used for future comparisons This specification does NOT cover runtime execution policy in GitHub Actions jobs.
1.3 Design Goals Section titled “1.3 Design Goals” Safe update enforcement is designed to preserve secure-by-default compilation while keeping compile output usable. The compiler SHALL produce actionable warnings and SHALL still generate lock files so subsequent compilations can compare against a baseline. 2. Conformance Section titled “2. Conformance” 2.1 Requirements Notation Section titled “2.1 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .
2.2 Conformance Classes Section titled “2.2 Conformance Classes” C1 (Compiler conformance) : Correctly activates safe update mode, resolves trusted baseline manifests, detects violations, and emits required warnings. C2 (Manifest conformance) : Emits parseable gh-aw-manifest metadata with deterministic normalization required for future safe update comparisons. 3. Safe Update Activation Model Section titled “3. Safe Update Activation Model” 3.1 Effective Safe Update Mode Section titled “3.1 Effective Safe Update Mode” Safe update mode MUST be enabled whenever effective strict mode is enabled and approval is not granted.
Effective strict mode MUST follow this precedence: CLI strict flag (enabled) Frontmatter strict boolean Default true when unspecified Safe update mode MUST be disabled when --approve is set, regardless of strict mode. 3.2 Strict-Mode Coupling Section titled “3.2 Strict-Mode Coupling” When frontmatter sets strict: false , safe update mode MUST be disabled and enforcement warnings MUST NOT be emitted. 4. Baseline Manifest Resolution and Trust Section titled “4.
Baseline Manifest Resolution and Trust” 4.1 Resolution Order Section titled “4.1 Resolution Order” When safe update mode is enabled, baseline manifest lookup MUST use this precedence: Pre-cached prior manifest supplied by caller Existing lock file content from git HEAD Existing lock file content from filesystem Empty non-nil manifest when no lock file exists 4.2 Legacy Lock Files Section titled “4.2 Legacy Lock Files” If a lock file exists but has no gh-aw-manifest , enforcement MUST be skipped for that compilation and MUST NOT produce violation warnings from missing baseline data.
4.3 Baseline Cache Stability Section titled “4.3 Baseline Cache Stability” When a non-nil baseline manifest is resolved, the compiler SHOULD retain that first trusted baseline for the current compiler instance and SHOULD NOT overwrite it with just-generated local results in subsequent compiles. 5. Violation Detection Rules Section titled “5. Violation Detection Rules” 5.1 Secret Violations Section titled “5.1 Secret Violations” Secret names MUST be normalized by removing the secrets. prefix before comparison.
The following secrets MUST always be allowed even when absent from prior manifest data: GITHUB_TOKEN GH_AW_GITHUB_TOKEN GH_AW_GITHUB_MCP_SERVER_TOKEN GH_AW_AGENT_TOKEN GH_AW_CI_TRIGGER_TOKEN GH_AW_PROJECT_GITHUB_TOKEN COPILOT_GITHUB_TOKEN Any other normalized secret name not present in the baseline manifest MUST be reported as a violation. 5.2 Action Violations Section titled “5.2 Action Violations” Action comparison MUST use repository identity (owner/repo) as the key.
Pin or version changes for an already approved repository MUST NOT be treated as violations. Compiler implementations MUST report: added unapproved action repositories removed previously approved action repositories The following repositories MUST be treated as trusted and MUST NOT generate add/remove violations: actions/* github/gh-aw/actions/* github/gh-aw-actions/* runtime-manager trusted repositories defined by compiler runtime mapping 5.3 Redirect Violations Section titled “5.3 Redirect Violations” Redirect values MUST be whitespace-trimmed before comparison.
If redirect changes relative to baseline, the compiler MUST report: newly added redirect removed previously approved redirect both signals when one redirect is replaced by another 5.4 Event Escalation Violations Section titled “5.4 Event Escalation Violations” The compiler MUST report a security escalation when baseline event presence indicates pull_request only, and current event presence indicates pull_request_target only.
Adding pull_request_target while retaining pull_request MUST NOT be treated as an event escalation violation. 6. Compiler Output and Approval Flow Section titled “6. Compiler Output and Approval Flow” 6.1 Warning-Only Enforcement Section titled “6.1 Warning-Only Enforcement” Safe update violations MUST be emitted as warnings, not hard compilation failures. Compilation MUST continue, and lock output SHOULD still be written.
6.2 Warning Content Section titled “6.2 Warning Content” Violation output MUST include: grouped violation details (secrets, added/removed actions, redirect changes, event escalation) remediation guidance that includes approval and revert options A security-review prompt SHOULD instruct calling agents to review the flagged changes and include a review note in pull request descriptions. 6.3 Approval Behavior Section titled “6.3 Approval Behavior” When --approve is provided, safe update enforcement MUST be skipped for that compile invocation.
6.4 First-Compile Baseline Establishment Section titled “6.4 First-Compile Baseline Establishment” For workflows with no prior lock file, compilers MUST compare against an empty non-nil baseline, surface new restricted changes as warnings, and emit a lock file with gh-aw-manifest so future compiles have baseline state. 7. Manifest Format Requirements Section titled “7. Manifest Format Requirements” 7.1 Manifest Header Section titled “7.1 Manifest Header” Compiled lock files MUST embed a single-line JSON manifest comment in header form: # gh-aw-manifest: { ... } 7.2 Required and Optional Fields Section titled “7.2 Required and Optional Fields” Manifest payloads MUST include version , secrets ,
The rest of this page is on the live site.