Conversation
…tent Consolidate phases 2-5 into a table, condense the "Why Detection..." section subsections, and tighten the overview and debugging sections. All technical content preserved. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This was referenced Mar 5, 2026
pelikhan
approved these changes
Mar 5, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Reduces length of the compilation-process reference doc by consolidating and tightening several sections while aiming to preserve technical content.
Changes:
- Rewrote the Overview to remove a redundant step list and tighten phrasing.
- Consolidated compilation Phases 2–5 into a single table.
- Condensed multiple subsections (execution-flow explanation, security/job-separation rationale, action pinning, debugging “common issues”).
Comments suppressed due to low confidence (3)
docs/src/content/docs/reference/compilation-process.md:170
- The gating condition is written as
success == 'true', which isn’t a valid/recognizable GitHub Actions context on its own and doesn’t match the current compiled workflows (which gate onneeds.agent.outputs.detection_success == 'true'). Please reference the actual output/context used for the threat-detection gate.
The system enforces [Plan-Level Trust](/gh-aw/introduction/architecture/) — separating AI reasoning (read-only) from write operations. The **detection** job runs its own AI engine as a security gate: `success == 'true'` is the explicit condition controlling whether `safe_outputs` executes at all. If combined, a compromised agent's output could bypass detection.
docs/src/content/docs/reference/compilation-process.md:186
- The safe-outputs gating expression is documented as
needs.detection.outputs.success == 'true', but current compiled workflows gate on the agent job’s output (needs.agent.outputs.detection_success == 'true') because threat detection runs inline in the agent job. Please update the condition here (and keep any other required guards like!cancelled()/needs.agent.result != 'skipped'if you want to show the fullif:).
The `safe_outputs` job condition (`needs.detection.outputs.success == 'true'`) ensures the runner **never starts** if detection fails — write-permission code never loads. Step-level `if` conditions within a single job provide weaker isolation.
docs/src/content/docs/reference/compilation-process.md:206
- This resolution-order summary claims to mirror Phase 4, but Phase 4’s table also includes the final step of adding a version comment (and previously mentioned caching the resolved pin). Either include the missing step(s) here or rephrase so it’s clear you’re only describing the resolution sources, not the full process.
All GitHub Actions are pinned to commit SHAs (e.g., `actions/checkout@b4ffde6...11 # v6`) to prevent supply chain attacks. Tags can be moved to malicious commits, but SHA commits are immutable. The resolution order mirrors Phase 4: cache (`.github/aw/actions-lock.json`) → GitHub API → embedded pins.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| ## Overview | ||
|
|
||
| The `gh aw compile` command transforms a markdown file into a complete GitHub Actions workflow by embedding the frontmatter and setting up runtime loading of the markdown body. The GitHub Actions workflow will have multiple orchestrated jobs. | ||
| The `gh aw compile` command transforms a markdown workflow file into a complete GitHub Actions `.lock.yml` by embedding frontmatter and setting up runtime loading of the markdown body. The process runs five compilation phases (parsing, validation, job construction, dependency resolution, and YAML generation) described below. |
There was a problem hiding this comment.
The Overview lists five phases but omits action pinning, while the phase table below includes "4 Action Pinning" and Phase 1 combines parsing+validation. Please align the phase list with the headings used in this doc (e.g., include action pinning and/or use the same grouping/names as Phase 1 and Phases 2–5).
This issue also appears on line 206 of the same file.
Suggested change
| The `gh aw compile` command transforms a markdown workflow file into a complete GitHub Actions `.lock.yml` by embedding frontmatter and setting up runtime loading of the markdown body. The process runs five compilation phases (parsing, validation, job construction, dependency resolution, and YAML generation) described below. | |
| The `gh aw compile` command transforms a markdown workflow file into a complete GitHub Actions `.lock.yml` by embedding frontmatter and setting up runtime loading of the markdown body. The process runs five compilation phases (parsing and validation, job construction, dependency resolution, action pinning, and YAML generation) described below. |
| **Execution flow**: Pre-activation validates permissions → Activation prepares context → Agent executes AI → Detection scans output → Safe outputs run in parallel → Add comment waits for created items → Conclusion summarizes results. | ||
|
|
||
| Safe output jobs without cross-dependencies run concurrently for performance. When threat detection is enabled, safe outputs depend on both agent and detection jobs. | ||
| **Execution flow**: Pre-activation validates permissions → Activation prepares context → Agent executes AI → Detection scans output → Safe outputs run in parallel → Add comment waits for created items → Conclusion summarizes results. Safe output jobs without cross-dependencies run concurrently; when threat detection is enabled, safe outputs depend on both agent and detection jobs. |
There was a problem hiding this comment.
This sentence says safe outputs depend on both the agent and a separate detection job when threat detection is enabled, but the compiler implements threat detection inline in the agent job and gates downstream jobs via needs.agent.outputs.detection_success (no standalone detection job). Please update this execution-flow description to match the current job graph / gating mechanism.
This issue also appears in the following locations of the same file:
- line 170
- line 186
Suggested change
| **Execution flow**: Pre-activation validates permissions → Activation prepares context → Agent executes AI → Detection scans output → Safe outputs run in parallel → Add comment waits for created items → Conclusion summarizes results. Safe output jobs without cross-dependencies run concurrently; when threat detection is enabled, safe outputs depend on both agent and detection jobs. | |
| **Execution flow**: Pre-activation validates permissions → Activation prepares context → Agent executes AI and runs inline threat detection → Safe-output jobs start only if the agent’s detection check succeeds (for example, `needs.agent.outputs.detection_success == 'true'`) and run in parallel where there are no cross-dependencies → Add comment waits for created items → Conclusion summarizes results. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Removes documentation bloat from
docs/src/content/docs/reference/compilation-process.md, reducing the file from 376 lines to 303 lines (73 lines / ~19.4% reduction).Changes Made
Consolidated Phases 2–5 into a table (~31 lines saved)
The four brief phase sections (Job Construction, Dependency Resolution, Action Pinning, YAML Generation) each had only a bullet list and were reformatted into a single compact table, making the parallel structure explicit and scannable.
Condensed "Why Detection, Safe Outputs, and Conclusion Are Separate Jobs" subsections (~30 lines saved)
Sections 1 and 3–7 contained verbose explanations that repeated context from the surrounding text or the job-permissions table above them:
yamlcode block (condition already in prose)Tightened the Overview section (~9 lines saved)
Removed the numbered process list (Parsing, Validation, Job Building…) since it duplicated the Phase headings directly below.
Condensed Debugging "Common issues" (~3 lines saved)
Converted 3 separate bullet points to a single inline list.
Shortened Action Pinning section (~2 lines saved)
Removed "Resolution process" paragraph that repeated the Phase 4 table content.
Essential Content Preserved
Screenshots
Screenshots could not be captured: Playwright is sandboxed and could not reach the preview server's network address (
172.30.0.20:4322). The documentation build completed successfully with no errors (127 page(s) built in 35.56s, all internal links valid).References: