Skip to content

tutorial.md

Latest commit

 

History

History
105 lines (68 loc) · 2.76 KB

tutorial.md

File metadata and controls

105 lines (68 loc) · 2.76 KB

🚀 Tutorial — Get a workflow running in minutes

This short, hands-on tutorial will get you from zero to a running agentic workflow. You'll install the extension, add a sample workflow, set up the required secrets, compile the workflow to a lock file, and run it. Ready? Let's go! 🎉

What you'll do

  • Install the gh-aw extension
  • Add the sample weekly-research workflow to your repository
  • Add the required AI API key secret
  • Compile and run the workflow
  • Inspect logs and iterate

Prerequisites

  • GitHub CLI (gh) installed and authenticated. Check with:
gh auth status
gh --version
  • A repository you can push to (or a fork) and permission to add Actions secrets.

Step 1 — Install the extension

gh extension install githubnext/gh-aw

Verify that gh aw is available:

gh aw --help
gh aw version

Step 2 — Add a sample workflow

The easiest way to get started is to add a sample from the Agentics collection. From your repository root run:

gh aw add weekly-research -r githubnext/agentics --pr

This creates a pull request that adds .github/workflows/weekly-research.md and the compiled .lock.yml. Review and merge the PR into your repo.

Step 3 — Add an AI secret

Agentic workflows use an AI engine. For Claude add this repository secret:

gh secret set ANTHROPIC_API_KEY -a actions --body "<your-anthropic-api-key>"

For Codex (experimental), add:

gh secret set OPENAI_API_KEY -a actions --body "<your-openai-api-key>"

These secrets are used by Actions at runtime.

Step 4 — Compile and preview

Generate the compiled workflow file (.lock.yml) from your markdown source:

gh aw compile

To watch for edits while authoring (useful during development):

gh aw compile --watch

Step 5 — Run the workflow

Trigger the workflow immediately (local execution or dispatch, depending on your setup):

gh aw run weekly-research

Download and inspect execution logs:

gh aw logs weekly-research

Troubleshooting & diagnostics

  • gh aw status — Check workflow installation status
  • gh aw logs — Download recent run logs and cost/usage analysis
  • gh aw mcp-inspect — Inspect MCP servers and tools
  • If compilation fails, run gh aw compile --verbose for more details and follow the error output.

What's next?

You did it — you're ready to start automating with agentic workflows! ✨