Quick Start Guide

This guide will get you from zero to a running agentic workflow in minutes. You’ll install the extension, add a sample workflow, set up the required secrets, and run it.

🚀 Quick Start

Prerequisites

A repository you are a maintainer of, can push to (or a fork) and have permission to add Actions secrets.
A Claude or OpenAI API key.

Step 1 — Install the extension

Install the GitHub CLI.
Install the GitHub Agentic Workflows extension:

gh extension install githubnext/gh-aw

If this step fails, you may need to use a personal access token or run the install-gh-aw.sh script.

Step 2 — Add a sample workflow, review and merge

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 — Trigger a run of the workflow in GitHub Actions

Trigger the workflow immediately in GitHub Actions:

gh aw run weekly-research

After a few moments, you can check the status of the run:

gh aw status

Once the run is complete, a new issue will be created in your repository with a research report! The report will be automatically generated by the AI based on recent developments in your field, and will be refreshed every week.

📝 Understanding Your First Workflow

Let’s look at what you just added. The weekly research workflow automatically triages new issues:

---
on:
  schedule:
    - cron: "0 9 * * 1"  # Every Monday at 9 AM

safe-outputs:
  create-issue:
---

# Weekly Research Report

Create a weekly research report summarizing recent developments in our field:

1. Research recent developments and trends
2. Summarize key findings
3. Create an issue with the research report
4. Tag relevant team members

Keep the report concise but informative.

This workflow:

Triggers every Monday at 9 AM via cron schedule
Has permissions to read repository content and write issues
Uses tools to create GitHub issues
Runs AI instructions in natural language to create research reports

What’s next?

Now that you have your first workflow running:

Customize the workflow — Edit the .md file to fit your needs, then recompile with gh aw compile
Explore more samples — Check out The Agentics repository
Learn the concepts — Read Concepts to understand how agentic workflows work

You’re ready to start automating with agentic workflows! ✨