Quick Start

Caution

GitHub Agentic Workflows is a research demonstrator in early development and may change significantly. Using agentic workflows means giving AI agents (autonomous AI systems) the ability to make decisions and take actions in your repository. This 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

Before installing, ensure you have:

• ✅ GitHub CLI v2.0.0+ installed and authenticated (gh auth login)
• ✅ GitHub account with admin or write access to a repository
• ✅ GitHub Actions enabled in your repository
• ✅ Git installed on your machine
• ✅ Operating System: Linux, macOS, or Windows with WSL

Verify your setup:

gh --version      # Should show version 2.0.0 or higher
gh auth status    # Should show "Logged in to github.com"
git --version     # Should show git version 2.x or higher

Agentic Setup

If you want to use Copilot to configure GitHub Agentic Workflows, run:

npx --yes @github/copilot -i "activate https://raw.githubusercontent.com/githubnext/gh-aw/refs/heads/main/install.md"

How Agentic Workflows Work

Before installing anything, it helps to understand the workflow lifecycle:

1. You write       2. Compile           3. GitHub Actions runs
   .md file    →    gh aw compile   →    .lock.yml file
   (natural         (translates to        (GitHub Actions
   language)        GitHub Actions)       executes)

Why two files?

• .md file: Human-friendly markdown with natural language instructions and simple YAML configuration. This is what you write and edit.
• .lock.yml file: Machine-ready GitHub Actions YAML with security hardening applied. This is what GitHub Actions runs.
• Compilation: The gh aw compile command translates your markdown into validated, secure GitHub Actions YAML.

Think of it like writing code in a high-level language (Python, JavaScript) that gets compiled to machine code. You write natural language, GitHub runs the compiled workflow.

Important

Never edit .lock.yml files directly. These are auto-generated. Always edit the .md file and recompile with gh aw compile.

Step 1 — Install the extension

Working in GitHub Codespaces?

If you’re working in a GitHub Codespace (especially outside the githubnext organization), the extension installation may fail due to restricted permissions that prevent global npm installs. Use the standalone installer instead:

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

After installation, the binary is installed to ~/.local/share/gh/extensions/gh-aw/gh-aw and can be used with gh aw commands just like the extension installation.

Install the GitHub CLI, then install the GitHub Agentic Workflows extension:

gh extension install githubnext/gh-aw

Step 2 — Add a sample workflow

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

gh aw add githubnext/agentics/daily-team-status --create-pull-request

This creates a pull request that adds .github/workflows/daily-team-status.md and the compiled .lock.yml (the generated GitHub Actions workflow file). Review and merge the PR into your repo.

Step 3 — Add an AI secret

Agentic workflows need to authenticate with an AI service to execute your natural language instructions. By default, they use GitHub Copilot as the coding agent (the AI that executes your workflow instructions).

To allow your workflows to use Copilot, you’ll create a token and add it as a repository secret.

Create a Personal Access Token (PAT)

Create a Personal Access Token to authenticate your workflows with GitHub Copilot:

1. Visit https://github.com/settings/personal-access-tokens/new
2. Configure the token:
   • Token name: “Agentic Workflows Copilot”
   • Expiration: 90 days (recommended for testing)
   • Resource owner: Your personal account (required for Copilot Requests permission)
   • Repository access: “Public repositories” (required for Copilot Requests permission to appear)
3. Add permissions:
   • In “Account permissions” (not Repository permissions), find “Copilot Requests”
   • Set to “Access: Read”
4. Click “Generate token” and copy it immediately (you won’t see it again)

Can’t find Copilot Requests permission?

Requires an active GitHub Copilot subscription, a fine-grained token (not classic), personal account as Resource owner, and “Public repositories” or “All repositories” selected. Contact your GitHub administrator if Copilot is managed by your organization.

Add the token to your repository

Store the token as a repository secret:

1. Go to your repository → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Set Name to COPILOT_GITHUB_TOKEN and paste the token in Secret
4. Click Add secret

Repository secrets are encrypted and only accessible to workflows in your repository. See GitHub Copilot CLI documentation for more details.

Verify your setup

Before running workflows, verify everything is configured correctly:

gh aw status

Expected output:

Workflow                 Engine    State     Enabled  Schedule
──────────────────────────────────────────────────────────────
daily-team-status        copilot   ✓         Yes      0 9 * * 1-5

This confirms the workflow is compiled, enabled, and scheduled correctly.

Troubleshooting

If the workflow isn’t listed, run gh aw compile and verify .github/workflows/daily-team-status.md exists. If errors occur when running, verify the COPILOT_GITHUB_TOKEN secret is set with “Copilot Requests” permission and hasn’t expired. Run gh aw secrets bootstrap --engine copilot to check configuration.

Step 4 — Trigger a workflow run

Trigger the workflow immediately in GitHub Actions:

gh aw run daily-team-status

After a few moments, check the status:

gh aw status

Once complete, a new issue will be created in your repository with daily news! The report will be automatically generated by the AI based on recent activity in your repository.

Understanding Your First Workflow

The daily team status workflow creates a status report every weekday and posts it as an issue:

---
on:
  schedule:
    - cron: "0 9 * * 1-5"
  workflow_dispatch:
permissions:
  contents: read
  issues: read
  pull-requests: read
network: defaults
tools:
  github:
safe-outputs:
  create-issue:
---

# Daily Team Status

Create an upbeat daily status report for the team as a GitHub issue.
- Recent repository activity (issues, PRs, releases, code changes)
- Team productivity suggestions and improvement ideas
- Community engagement highlights
- Project investment and feature recommendations

...

1. Gather recent activity from the repository
2. Create a new GitHub issue with your findings and insights

Customize Your Workflow

Edit the .md file and recompile with gh aw compile. For AI-assisted customization using GitHub Copilot CLI:

npm install -g @github/copilot-cli
gh aw init
copilot
> /agent
> select create-agentic-workflow
> edit @.github/workflows/daily-team-status.md

What’s next?

Use Authoring Agentic Workflows to create workflows with AI assistance, explore more samples in the agentics repository, and learn about workflow management in Packaging & Distribution. To understand how agentic workflows work, read How It Works.