Editing Workflows

Agentic workflows have two parts: the YAML frontmatter, which is compiled into the lock file and requires recompilation when changed, and the markdown body, which is loaded at runtime and takes effect on the next run. This lets you iterate on instructions quickly while keeping security-sensitive configuration behind compilation.

See Creating Agentic Workflows for guidance on creating workflows with AI assistance.

Tip

Working in github/gh-aw itself? Treat any edit under .github/workflows/*.md as a cue to run make recompile before committing. CI checks the generated .lock.yml files for drift, so this is the safest default even when you’re only changing markdown instructions. For early feedback while iterating locally, you can run gh aw compile --watch --schedule-seed github/gh-aw, then finish with make recompile.

Editing Without Recompilation

You can edit the markdown body directly on GitHub.com or in any editor without recompiling. That includes instructions, output templates, conditional guidance, context, and examples.

Example: Adding Instructions

Before (in .github/workflows/issue-triage.md):

---
on:
  issues:
    types: [opened]
---

# Issue Triage

Read issue #${{ github.event.issue.number }} and add appropriate labels.

After (edited on GitHub.com):

---
on:
  issues:
    types: [opened]
---

# Issue Triage

Read issue #${{ github.event.issue.number }} and add appropriate labels.

## Labeling Criteria

Apply labels for bugs, enhancements, questions, and documentation updates. For priority, use `high-priority` for security or blocking issues, `medium-priority` for important but non-critical work, and `low-priority` for minor improvements.

✓ This change takes effect immediately without recompilation. In github/gh-aw, still run make recompile before committing so CI sees fresh .lock.yml files alongside the markdown change.

Editing With Recompilation Required

Caution

Changes to the YAML frontmatter always require recompilation because they affect security-sensitive configuration.

Any change between the --- markers requires recompilation, including triggers (on:), permissions, tools, network settings, safe outputs, MCP scripts, runtimes, imports, custom jobs, engine selection, timeouts, and roles.

Example: Adding a Tool (Requires Recompilation)

Before:

---
on:
  issues:
    types: [opened]
---

After (must recompile):

---
on:
  issues:
    types: [opened]

tools:
  github:
    toolsets: [issues]
---

! Run gh aw compile my-workflow before committing this change.

Expressions in Markdown

You can use these expressions in markdown without recompilation:

# Process Issue

Read issue #${{ github.event.issue.number }} in repository ${{ github.repository }}.

Issue title: "${{ github.event.issue.title }}"

Use sanitized content: "${{ steps.sanitized.outputs.text }}"

Actor: ${{ github.actor }}
Repository: ${{ github.repository }}

These expressions are evaluated at runtime and validated for security. See Templating for the complete list of allowed expressions.

Arbitrary expressions are blocked for security. This will fail at runtime:

# ✗ WRONG - Will be rejected
Run this command: ${{ github.event.comment.body }}

Use steps.sanitized.outputs.text for sanitized user input instead.

Recompiling with a Stable Schedule Seed

If a workflow uses fuzzy schedules such as daily, weekly, or every 2h, recompilation can change the generated cron output when the compiler derives its scatter seed from repository metadata that differs across clones.

For shared repositories, pass a canonical repository slug with --schedule-seed so every contributor generates the same cron expressions:

gh aw compile --schedule-seed github/gh-aw

The repository Makefile uses this pattern in make recompile:

make recompile

Use a fixed seed whenever deterministic schedule output matters, especially for workflows committed to version control.

Quick Rule of Thumb

Edit the markdown body for instruction changes, and recompile after any frontmatter change. Use --schedule-seed or a project make recompile target when fuzzy schedules must compile deterministically across contributors, and use sanitized step outputs instead of raw user input in expressions.

Related Documentation

• Workflow Structure for file organization
• Frontmatter Reference for configuration options
• Markdown Reference for writing instructions
• Compilation Process for compilation details
• Templating for expression syntax
• Workshop for hands-on exercises