Quick Start

Get your first agentic workflow running in minutes. Install the extension, add a sample workflow, configure your AI engine, and trigger your first run. You’ll have a working example demonstrating AI-powered automation in your repository.

Caution

GitHub Agentic Workflows is a research demonstrator in early development and may change significantly. Using agentic workflows requires careful attention to security considerations and human supervision. Review all outputs carefully and use time-limited trials to evaluate effectiveness for your team.

Prerequisites

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 (PAT) for GitHub Copilot CLI, or an Anthropic Claude or OpenAI API key.

Step 1 — Install the extension

Install the GitHub CLI, then 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

Add a sample from the agentics collection. From your repository root run:

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 “Resource owner”, select your user account (not an organization, see note below).

3. Under “Repository access,” select “Public repositories”

4. Under “Permissions,” click “Add permissions” and select “Copilot Requests”. If you are not finding this option, review steps 2 and 3.

5. Generate your token

6. Add the token to your repository secrets as COPILOT_GITHUB_TOKEN:

   gh secret set COPILOT_GITHUB_TOKEN -a actions --body "<your-personal-access-token>"

Note

There is an ongoing work to support authentication with the GitHub Action token. Once this work is deployed, you will not need to create a token for Copilot CLI.

For more information, see the GitHub Copilot CLI documentation.

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

Step 4 — Trigger a workflow run

Trigger the workflow immediately in GitHub Actions:

gh aw run weekly-research

After a few moments, check the status:

gh aw status

Once 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

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?

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
• Write workflows with an agent — Use Authoring Agentic Workflows to create workflows with AI assistance in your editor
• Explore more samples — Check out the agentics repository
• Learn about adding and updating workflows — Read Packaging & Distribution to understand workflow management
• Understand the concepts — Read How It Works to understand how agentic workflows work

You’re ready to start automating with agentic workflows!