GitHub Agentic Workflows: Markdown Intent, Compiled Controls
Understand gh-aw source and lock files, read-only execution, safe outputs, and a local compilation exercise before enabling repository automation.
Describe the task, but lock down the machinery
A traditional workflow says exactly which commands run in which order. An agentic workflow can ask an AI engine to interpret context and choose actions within configured boundaries. That flexibility is useful for triage or investigation, but it does not make access control optional.
GitHub Agentic Workflows uses Markdown with YAML frontmatter as source. The gh-aw tooling compiles that source into an Actions .lock.yml workflow. GitHub Actions executes the generated workflow; a Markdown file alone is not a running schedule.
Version note, 30 October 2026: this is a rapidly evolving project. The official project documentation is the authority for supported syntax, engines, authentication, and availability. Do not assume exam inclusion means universal GA availability or free inference. Check your organization’s policies and selected engine’s access/billing before enabling a run.
Keep the pieces separate
| Piece | Purpose |
|---|---|
| Markdown body | Task instructions and expected behavior |
| YAML frontmatter | Triggers, tools, engine, permissions, and outputs |
| Compiler | Validate and produce executable workflow configuration |
.lock.yml | Generated Actions workflow reviewed and committed with source |
| Safe outputs | Constrained, validated route for supported writes |
| Engine authentication | Access to the selected AI execution service |
This is not the same as assigning an issue directly to Copilot cloud agent, and it is not simply a normal YAML file containing a conversational prompt.
Start with a read-only, manually triggered task
In a disposable repository, an illustrative source .github/workflows/repository-summary.md is:
---
on: workflow_dispatch
permissions:
contents: read
engine: copilot
safe-outputs:
create-issue: false
tools:
github:
toolsets: [repos]
---
# Repository summary
Inspect the repository's existing README and file structure.
Summarize what is directly supported by those files.
Do not modify files, create issues, comment, or request broader access.
If evidence is missing, report that limitation.Confirm this shape with the installed compiler’s current schema; supported toolsets and engine settings can evolve. The task is intentionally read-only and manual. It does not need issue creation or deployment credentials.
The explicit create-issue: false matters: the current compiler automatically enables a constrained issue-creation output when safe-outputs is absent or contains only system outputs. Read-only permissions on the agent job alone do not disable that separate write-capable reporting job. Do not rely on the instruction “do not create issues” to remove a capability the configuration still permits.
Following the current project setup instructions, a learner with GitHub CLI can install the reviewed extension and compile:
gh extension install github/gh-aw
gh aw compileInstalling an extension executes third-party tooling, so use an approved source and review version/provenance. Do this in your own sandbox, not an organization’s production checkout. Compilation creates or updates generated files; inspect the diff.
Read both the frontmatter and generated workflow. Check events, job permissions, engine authentication requirements, tool access, network boundaries, time limits, and output handling. Compilation success demonstrates syntax acceptance, not safe behavior or factual accuracy.
Add writes only through a deliberate design
For a triage workflow that needs to comment, the documented recommended pattern uses an allowed safe output such as:
safe-outputs:
add-comment:This is a configuration fragment, not a complete workflow. Review the current safe-output schema, target constraints, limits, and generated permission-bearing jobs before using it.
Safe outputs keep the agent job read-only by default and handle supported writes through a separate controlled path. They do not prove that the generated content is true, welcome, or appropriate. Direct write permissions and custom jobs form additional trust boundaries; they are not made harmless by the presence of a safe-output section elsewhere.
Do not grant unrestricted shell/network tools or broad token scope just to avoid a failed task. A natural-language instruction such as “never deploy” is not equivalent to withholding deployment credentials and tools.
Test against malicious or incomplete input
Issue bodies and repository documents are untrusted task data. A workflow summarizing an issue may encounter text that asks it to reveal secrets or ignore its instructions. Bound the tools, data exposure, write destinations, and run duration independently of the prompt.
Evaluate ordinary input, missing context, and an instruction-injection attempt in a sandbox without secrets. Inspect run logs and outputs. A task that cannot complete should fail or explain the missing evidence, not fabricate success.
Before enabling a schedule, identify an owner, budget, cancellation path, output audience, and evidence retention. Autonomous posting is a real external action, not merely a local draft.
A Markdown agentic workflow compiles successfully. Which conclusion is justified?
Try it: compile without running
Prerequisites: GitHub CLI and permission to install the approved extension in your own environment. No agent execution, issue posting, or paid inference is required for this local compilation exercise.
Create the read-only manual source in a disposable repository, run the current compiler, and inspect its generated lock file. Record which permissions and tools it grants. If compilation rejects a field, consult the current schema rather than replacing it with a broad default.
Expected observation: a source/lock pair exists and its configured execution boundaries can be explained. No workflow has run simply because compilation succeeded.
Cleanup: remove the disposable source and generated lock file. If you later enable a sandbox run, configure engine access deliberately and disable it afterwards; do not leave an unattended schedule behind.
Decision check: deterministic YAML or agentic workflow?
Keep deterministic build/test/deploy mechanics in predictable automation when interpretation adds no benefit. Use bounded agentic work for tasks that genuinely require reading context or proposing conclusions.