# Automate unstructured repo work with GitHub Agentic Workflows > Install gh aw, initialise the repo, have a coding agent write a Markdown workflow, compile it to lock.yml, commit both, and put a drift check in CI so you never ship Markdown without its compiled Actions file. - **Category:** [Coding](https://stepgleam.com/categories/coding) - **Difficulty:** Intermediate - **Time:** ~40 minutes - **Tools:** GitHub Agentic Workflows, gh aw CLI, GitHub Copilot CLI - **Reliability score:** 82/100 - **Steps:** 6 - **Last updated:** 2026-10-29 - **Published:** 2026-10-29 ## Tools used - [GitHub Agentic Workflows](https://docs.github.com/en/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/about-github-agentic-workflows) — Markdown workflows that compile to Actions and run a coding agent - [gh aw CLI](https://github.com/github/gh-aw) — Init, compile and run agentic workflows - [GitHub Copilot CLI](https://docs.github.com/en/copilot) — Default engine Fränkel used to author the Markdown workflow ## What you'll get A Markdown agentic workflow plus its compiled .lock.yml in .github/workflows/, running on Actions with safe-outputs, and a CI check that fails if the lock file drifts. ## Who this is for Teams with GitHub Actions enabled who need an agent for semi-structured repo work (release notes, triage, docs) that deterministic scripts cannot parse. ## Before you start GitHub Agentic Workflows went generally available on 28 October 2026. Nicolas Fränkel (long-time HN account) used them earlier in 2026 to parse unstructured release notes for deprecations that no regex could catch, then reused the same lessons to keep README, wiki, Copilot instructions and changelog in sync. This guide sticks to his write-up and the official docs. Gaps he left (the exact release-notes prompt, the full CI YAML) are left as gaps. ## Steps ### Step 1: Install the gh aw extension and initialise the repo **Tool:** gh aw CLI Fränkel's kickoff: install the `gh` aw extension, then run `gh aw init` (or use the GitHub GUI). Official docs say `gh aw init` adds skills and instructions so a coding agent can create and edit workflows more effectively. **Why this works:** Without the skills from init, the coding agent has no project-local guidance for this format. **Prompt:** ``` gh extension install github/gh-aw && gh aw init ``` [Open step 1](https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows#step-1) ### Step 2: Ask a coding agent to create the Markdown workflow with the agentic-workflows skill **Tool:** GitHub Copilot CLI Fränkel used Copilot CLI for "development proper." The docs recommend starting your coding agent in the repo and prompting with the `agentic-workflows` skill, for example a PR reviewer or a daily activity report. The agent creates a Markdown file under `.github/workflows/` with YAML frontmatter (`on`, `permissions`, `safe-outputs`, `engine`) and a natural-language body. **Prompt:** ``` /agentic-workflows Create a workflow that reviews each pull request and checks that the changes include enough tests. ``` [Open step 2](https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows#step-2) ### Step 3: Compile the Markdown to .lock.yml before you push **Tool:** gh aw CLI Fränkel's first hard lesson: *"GitHub doesn't execute the Markdown workflow, but the YAML one."* He once pushed only the Markdown and saw no change. Compile with `gh aw compile` (or `gh aw compile my-workflow`). Commit both files. Docs say the same: commit the `.md` and the compiled `.lock.yml`. **Why this works:** Actions only sees the compiled YAML; Markdown alone is a silent no-op. **Prompt:** ``` gh aw compile --validate --strict ``` [Open step 3](https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows#step-3) ### Step 4: Add the engine token the workflow expects **Tool:** GitHub Agentic Workflows Fränkel: the compiled workflow looks for `GITHUB_COPILOT_TOKEN`, a fine-grained token with at least Copilot requests permission. Docs add that each engine (Copilot, Claude, Codex, Gemini) needs its own authentication secret in the repository, and Copilot is the default when `engine` is omitted. [Open step 4](https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows#step-4) ### Step 5: Check lock-file drift in CI; do not let a workflow rewrite other workflows **Tool:** gh aw CLI Fränkel first tried a workflow that recompiled agentic workflows on change and hit permission issues. He decided that was a bad idea: *"if an attacker manages to control a workflow, they can do whatever the workflow's permissions allow."* His next best thing: a CI job that compiles under the same conditions and fails if the result differs from the committed lock files. On Windows vs Ubuntu he also needed a proper `.gitattributes` file for line endings. **Why this works:** A failing drift check catches a forgotten compile without giving the pipeline write access to workflow files. [Open step 5](https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows#step-5) ### Step 6: Pick a use case deterministic scripts cannot handle **Tool:** GitHub Agentic Workflows Fränkel's winning case was upgrade-impact config files: some deprecations lived in code (`@Deprecated`, custom annotations), but plugin deprecations lived only in unstructured release notes. *"I can't use standard deterministic automations. Release notes don't have a regular structure."* After that worked, he got continuous documentation working too: every relevant change opens a PR updating README, wiki, Copilot `instructions.md` and the changelog. He did not publish the exact system prompt for the release-notes job beyond GitHub's sandbox policy block. **Why this works:** Agents earn their keep on semi-structured text; keep regex for the structured half. [Open step 6](https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows#step-6) ## Pro tips - Commit both the .md and the .lock.yml; Actions runs the YAML, not the Markdown. - Keep write operations behind safe-outputs such as create-issue or create-pull-request. ## Common mistakes - Pushing only the Markdown and wondering why nothing runs. - Letting a workflow rewrite other workflows automatically; Fränkel hit permission walls and later called that a bad idea for security. ## FAQ ### Do I need Copilot? The default engine is Copilot and needs a Copilot license plus a fine-grained token with Copilot requests permission. The docs also list Claude, Codex and Gemini as engines with their own secrets. ### Can I use Marketplace actions inside an agentic workflow? Fränkel reports you cannot; basic jobs such as opening a PR have to be reinvented or done through safe-outputs. --- Canonical guide: https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows Read this guide as Markdown: https://stepgleam.com/guides/automate-unstructured-repo-work-with-github-agentic-workflows.md