🚀

Get Started

From zero to your first agentic workflow in minutes

Before You Begin

Prerequisites

✅ Required

  • A GitHub Copilot subscription (Individual, Business, or Enterprise)
  • GitHub CLI v2.45.0 or later
  • The gh-aw CLI extension
  • Admin access to the target repository

🔑 Tokens & Secrets

  • COPILOT_GITHUB_TOKEN — required for every workflow
  • GH_AW_AGENT_TOKEN — optional, needed for assign-to-agent
  • Custom PAT or GitHub App — optional, for cross-repo or elevated access
Setup

Install & Initialize

Three commands to go from zero to a fully initialized repository. The CLI handles scaffolding, engine selection, and configuration.

1

Install the gh-aw CLI extension

Adds the gh aw command to your GitHub CLI. Requires GitHub CLI v2.45.0 or later.

2

Initialize your repository

Run gh aw init —engine copilot to scaffold your repo. This creates copilot-setup-steps.yml, walks you through engine selection, and configures the necessary directory structure.

3

Create the required secret

Store your Copilot token as a repository secret so workflows can authenticate with the Copilot API.

Terminal
# 1. Install the gh-aw CLI extension
gh extension install github/gh-aw

# 2. Initialize your repository
gh aw init --engine copilot

# 3. Create the required secret
gh secret set COPILOT_GITHUB_TOKEN -R owner/repo

💡 What does gh aw init do? It creates the copilot-setup-steps.yml file that defines your agent’s runtime environment, walks you through engine selection (Copilot, Claude, or Codex), and sets up the .github/workflows/ directory for your first workflow.

Authentication

Create the COPILOT_GITHUB_TOKEN

Every agentic workflow needs a COPILOT_GITHUB_TOKEN to authenticate API calls. Here’s how to create one:

1

Generate a fine-grained token

Go to github.com/settings/personal-access-tokens/new and select Fine-grained personal access token.

2

Grant Copilot permission

Under Account permissions, set Copilot Requests to Read-only. No other permissions are required for the base token.

3

Store as a repository secret

Run gh secret set COPILOT_GITHUB_TOKEN -R owner/repo and paste the token when prompted — or add it via the repository Settings → Secrets → Actions page.

Secrets Reference

SecretWhen NeededPermission
COPILOT_GITHUB_TOKENAlways — every workflowCopilot Requests: Read-only
GH_AW_AGENT_TOKENUsing assign-to-agentIssues: Read & Write
ANTHROPIC_API_KEYUsing engine: claude—
OPENAI_API_KEYUsing engine: codex—
GEMINI_API_KEYUsing engine: gemini—
Build

Your First Workflow

Use the CLI to add a pre-built workflow template, compile it into a hardened GitHub Actions file, and push it to your repo.

1

Add a workflow from the gallery

The add-wizard command pulls a workflow template and saves it as a Markdown source file in .github/workflows/.

2

Compile to a hardened Actions workflow

The compile command transforms your Markdown source into a .lock.yml file with pinned actions, sandboxed permissions, and safe outputs.

3

Push to your repository

Commit both the .md source and the .lock.yml compiled file. GitHub Actions picks up the lock file automatically on the next trigger.

Terminal
# 1. Create a workflow from a template
gh aw add-wizard githubnext/agentics/daily-repo-status

# 2. Compile to a hardened Actions workflow
gh aw compile .github/workflows/daily-repo-status.md

# 3. Push both files to your repo
git add .github/workflows/
git commit -m "Add daily status report workflow"
git push

🎉 That’s it! Your workflow will now trigger automatically based on its configured events (schedule, issue creation, etc.). Check the Actions tab in your repository to see it run.