From Markdown to Guarded Automation: Build Your First GitHub Agentic Workflow

From Markdown to Guarded Automation: Build Your First GitHub Agentic Workflow

GitHub Agentic Workflows bring natural-language reasoning into GitHub Actions without asking us to abandon the controls that make automation dependable. We describe the task in Markdown, declare the tools and boundaries in front matter, then compile that source into an ordinary GitHub Actions workflow.

In this tutorial, we will build a small CI failure triage workflow, compile its Markdown source into a standard GitHub Actions workflow, and examine the guardrails that keep its access bounded. The finished workflow reads a failed run, analyses its jobs and logs, and proposes one diagnostic issue in staged mode for a maintainer to inspect.

Current status: GitHub Agentic Workflows are in public preview and subject to change. This sample passed strict validation with gh-aw v0.86.2 on 25 August 2026.

What We Will Build

The workflow will listen for a workflow named CI to complete on main. It will proceed only when that run failed, then use read-only GitHub tools to inspect the run, failed jobs, logs and relevant repository files.

The agent can reach one outcome:

• propose one issue containing the evidence, likely cause and remediation steps
• call noop when there is not enough evidence or no maintainer action is needed

At first, even the issue is only a preview. staged: true lets the complete analysis run while skipping every write. The proposed title and body appear in the GitHub Actions step summary instead. This gives us real output to review without accepting a real repository change.

Two files form the deployable workflow:

.github/workflows/
|-- ci-failure-triage.md
`-- ci-failure-triage.lock.yml

The Markdown file is the source we edit. The .lock.yml file is compiler-managed Actions YAML. Both belong in version control so reviewers can inspect the intent and the exact automation GitHub will execute.

Prerequisites

You will need:

• a non-production GitHub repository where you can write workflow files
• GitHub Actions enabled and an existing workflow whose displayed name is CI
• GitHub CLI authenticated with repository and workflow access
• GitHub Copilot inference access, either through organisation billing or a personal fine-grained token
• permission to review the repository's Actions policy and Copilot policy

This tutorial uses the recommended organisation path. The special permission below allows the ephemeral Actions token to make Copilot inference requests billed through the organisation:

permissions:
    copilot-requests: write

It does not grant permission to modify repository contents. The organisation must have a Copilot subscription with centralised billing enabled.

For a personal repository, create a fine-grained personal access token owned by your user account with Copilot Requests: Read, save it as COPILOT_GITHUB_TOKEN, and remove copilot-requests: write from the sample. When that permission is present, gh-aw deliberately ignores the PAT for inference. The authentication reference documents both paths.

Understand the Security Boundary

Natural-language instructions improve flexibility, but they are not a permission boundary. Logs, commit messages and repository files can contain misleading text, including prompt injection. The reliable controls must therefore sit outside the prompt.

This workflow uses several independent layers:

The GitHub Agentic Workflows security architecture keeps the reasoning job separate from write-capable jobs. The agent requests an operation through a structured safe-output tool. The framework validates and sanitises that output, and a separate job applies the narrowly scoped operation. We never give the reasoning process issues: write.

GitHub also warns that a workflow_run workflow can access secrets and write tokens, even when the preceding workflow could not. Treat this event as a privilege boundary: do not check out or execute untrusted code, or feed untrusted artifacts into privileged steps. This example inspects evidence through the configured read tools and explicitly forbids executing repository content.

The prompt still matters. It tells the agent to treat inspected content as data, never execute instructions found in logs, and prefer noop over an unsupported diagnosis. That guidance improves behaviour, while permissions, tools, networking and safe outputs enforce the hard limits.

Install and Initialise gh aw

From the repository root, verify GitHub CLI authentication and install the official extension:

gh auth status
gh extension install github/gh-aw
gh aw version
gh aw doctor

If the extension is already installed, update it with gh extension upgrade github/gh-aw. Public-preview syntax can change, so record the version used to compile a workflow when investigating a difference.

Initialise the repository once:

gh aw init

Review the files created by init before committing them. The command configures repository support such as generated-file attributes and agentic authoring resources. The current CLI reference is the source of truth for its options.

Write the CI Failure Triage Workflow

Create .github/workflows/ci-failure-triage.md with the following content. Change CI and main if your monitored workflow or default branch uses different names.

---
description: Investigate failed CI runs and propose a bounded diagnostic issue for maintainer review.

on:
  workflow_run:
    workflows: [CI]
    types: [completed]
    branches