gh-aw Quick Start — Your First Agentic Workflow

Lesson 2 · Safe Agentic Workflows · ~10 minutes

You already have GitHub Actions running CI/CD for your repos. In this lesson, you'll add something new alongside it: an agentic workflow — an AI agent that runs automatically on a schedule, analyzes your repository, and produces a daily status report.

Your existing .yml workflows stay untouched. You're adding a new kind of workflow file (written in Markdown) that compiles into its own Actions YAML. Two systems, one Actions tab, zero interference.

Prerequisites

Before you start, confirm these are in place:

GitHub CLI (gh) v2.0.0+ — check with gh --version. Install here if needed.
Logged in — verify with gh auth status. If scopes are missing, run gh auth login --scopes repo,workflow.
GitHub Actions enabled — check under Settings → Actions in your target repo.
AI account — GitHub Copilot (simplest if you already have it), Anthropic Claude, OpenAI Codex, or Google Gemini.
A repo where you have write access — pick a real one you maintain.

Already have Copilot?

If you have a GitHub Copilot subscription, start there. It requires no extra account setup — you'll just need to create a fine-grained PAT with the Copilot Requests permission.

Step 1: Install the Extension

gh extension install github/gh-aw

This adds the gh aw subcommand to your CLI. If you encounter authentication issues, you can also install via:

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

Step 2: Add a Workflow with the Wizard

Navigate to your repository root and run:

gh aw add-wizard githubnext/agentics/daily-repo-status

The reference format is <owner>/<repo>/<workflow-name>. This pulls the "Daily Repo Status" workflow from GitHub Next's public examples repository.

The Interactive Process

The wizard walks you through five steps:

add-wizard interactive flow

Check prerequisites Verifies you have write access and Actions are enabled.

Select an AI engine Choose between Copilot, Claude, Codex, or Gemini.

Set up the required secret Depending on your engine: COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY. The wizard tells you exactly what to create and where.

Add workflow files Creates two files in .github/workflows/ — the source markdown and its compiled lock file.

Optionally trigger an initial run Starts the workflow immediately so you can see results within minutes.

Setting up COPILOT_GITHUB_TOKEN

1. Create a fine-grained PAT under your account.
2. Under Permissions → Account permissions, set Copilot Requests to Read.
3. Add as a repo secret: gh secret set COPILOT_GITHUB_TOKEN < /path/to/token.txt

Step 3: What Gets Created

After the wizard completes, you have two new files:

.github/workflows/

daily-repo-status.md

The workflow source. Plain Markdown with YAML frontmatter (triggers, engine, permissions) and a prose body (the agent's instructions). This is what you edit.

daily-repo-status.lock.yml

The compiled Actions YAML. Auto-generated from the .md file. This is what GitHub Actions actually executes. Never edit this by hand — it gets regenerated.

This is the key mental model: you author in Markdown, the toolchain compiles to YAML. The .lock.yml includes all the Actions plumbing — checkout steps, engine setup, safe output jobs, secret redaction, threat detection — so you don't have to write any of it.

How This Fits Your Existing Setup

ci.yml
deploy.yml

Your existing Actions

daily-repo-status.md
daily-repo-status.lock.yml

New agentic workflow

They coexist in .github/workflows/. Different triggers, different jobs, no interaction.

Step 4: Trigger a Run

If you didn't trigger during the wizard, do it now:

gh aw run daily-repo-status

The workflow takes 2–3 minutes. While it runs, the agent reads your repository's recent activity — issues, PRs, discussions, releases, code changes — and generates a structured status report.

Step 5: Monitor

Two ways to watch:

CLI: gh aw status shows workflow state. gh run watch streams the latest run's logs.
Browser: Open the Actions tab and select the most recent run.

When the run succeeds, a new issue titled "Daily Repo Report" appears in your Issues tab. It includes recent activity analysis, progress tracking, project status, and recommended next steps.

Step 6: Customize

The workflow is yours now. To customize:

Open .github/workflows/daily-repo-status.md
Edit the body — change the "What to include" section to focus on what matters to you (backlog health, CI status, testing gaps, roadmap progress)
If you changed the frontmatter (the YAML between --- markers), regenerate the lock file:
```
gh aw compile
```
Commit and push
Trigger another run: gh aw run daily-repo-status

When do you need to recompile?

Only when you change the frontmatter (triggers, engine, permissions, network config). If you only edit the prose body (the agent's instructions), just commit and push — no recompilation needed.

Why Read-Only? The SafeOutputs Model

You might notice: the agent job runs with read-only permissions. It can read your code, issues, and PRs, but it cannot directly write to your repository. When it wants to create an issue (like the daily report), the output is buffered as an artifact, run through a threat detection pipeline, and only then handed to a separate job with scoped write permissions.

This is the SafeOutputs architecture — even a fully compromised agent cannot directly modify your repository. Write operations are deferred, validated, and executed by separate jobs with minimal permissions. It's defense-in-depth by design.

This connects directly to Lesson 1's Layer 1 (Hooks): the permission isolation is an enforced guardrail the agent cannot bypass.

Quick Reference

Command	What it does
`gh extension install github/gh-aw`	Install the extension
`gh aw add-wizard <ref>`	Add a workflow interactively
`gh aw run <name>`	Trigger a workflow run manually
`gh aw status`	Check workflow state
`gh aw compile`	Regenerate `.lock.yml` from `.md` frontmatter
`gh aw logs`	Download and analyze run logs

Check Your Understanding

What file format are gh-aw workflows written in?

YAML (.yml)
Markdown (.md) with YAML frontmatter
JSON (.json)
TOML (.toml)

Correct — you author workflows in Markdown. The frontmatter holds configuration (triggers, engine, permissions) and the body holds the agent's instructions in prose. The toolchain compiles this into the .lock.yml that Actions executes.

Not quite. gh-aw workflows are written in Markdown (.md) with YAML frontmatter for configuration. The .lock.yml (Actions YAML) is auto-generated — you never write it by hand.

What does gh aw compile do?

Runs the workflow and produces a report
Validates your AI engine credentials
Regenerates the .lock.yml file from the workflow's Markdown frontmatter
Installs dependencies needed by the workflow

Right — compile takes your .md source file and regenerates the compiled Actions YAML (.lock.yml). You run it after changing frontmatter configuration. Body-only edits don't need recompilation.

The compile command regenerates the .lock.yml (the Actions YAML) from your workflow's Markdown frontmatter. It's a build step, not a run step. You only need it when frontmatter changes.

Why does the agent job run with read-only permissions?

To reduce API rate limiting
Because GitHub doesn't support write permissions in Actions
So that even a compromised agent cannot directly modify repository state — writes are deferred to separate, validated jobs
To make workflows faster by skipping permission checks

Exactly — this is the SafeOutputs architecture. The agent buffers its intended actions as artifacts. A separate threat detection job validates them, and only then do scoped write jobs execute. Defense-in-depth: the agent never has the credentials to write directly.

The read-only constraint is a security design called SafeOutputs. The agent never gets write permissions — its outputs are buffered, validated by a threat detection pipeline, and only then executed by separate jobs with minimal scoped write access. This prevents a compromised agent from directly modifying your repo.

What's Next

You now have a working agentic workflow running in your repository. In the next lesson, we'll look at the security model — how safe outputs, sandboxing, and threat detection let you trust agents with increasing autonomy.

Primary Source

gh-aw Quick Start — the official guide this lesson is based on. Includes a video walkthrough and troubleshooting links.

Questions? If you hit a snag during setup, paste the error here. I can help troubleshoot authentication issues, secret configuration, and common failure modes.

← Back Next →