Skip to content
GitHub Agentic Workflows

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

Section titled “🚀 Quick Start”

Prerequisites

  • A repository you are a maintainer of, can push to (or a fork), with Actions, Discussions and Issues enabled, and you have permission to add Actions secrets.

  • A Personal Access Token for GitHub Copilot CLI, or an Anthropic Claude or OpenAI API key.

Step 1 — Install the extension

  • Install the GitHub CLI.

  • Install the GitHub Agentic Workflows extension:

Terminal window
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:

Terminal window
gh aw add githubnext/agentics/weekly-research --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 a coding agent: GitHub Copilot CLI (default), Claude or Codex.

For GitHub Copilot CLI, create a fine-grained Personal Access Token (PAT) with the “Copilot Requests” permission enabled:

  1. Visit https://github.com/settings/personal-access-tokens/new
  2. Under “Permissions,” click “add permissions” and select “Copilot Requests”
  3. Generate your token
  4. Add the token to your repository secrets as COPILOT_CLI_TOKEN:
Terminal window
gh secret set COPILOT_CLI_TOKEN -a actions --body "<your-personal-access-token>"

For more information, see the official documentation.

For Claude and Codex, see the instructions in AI Engines.

Step 4 — Trigger a run of the workflow in GitHub Actions

Trigger the workflow immediately in GitHub Actions:

Terminal window
gh aw run weekly-research

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

Terminal window
gh aw status

Once the run is complete, a new discussion post 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

Section titled “📝 Understanding Your First Workflow”

Let’s look at what you just added. The weekly research workflow automatically creates a research report every week and posts it as a discussion in your repository, and looks like this:

---
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?

Section titled “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 about adding and updating workflows — Read Packaging and Updating to understand workflow management
  • Learn the concepts — Read Concepts to understand how agentic workflows work

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