How to Set Up gh-aw in a New Repository: A Complete Guide

Run curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash to install the CLI, then execute gh aw init --engine copilot to scaffold the required configuration files.

GitHub Agentic Workflows (gh-aw) enables you to author GitHub Actions using natural-language Markdown and execute them with AI assistance. Setting up the github/gh-aw toolchain in a fresh repository requires three distinct phases: installing the CLI extension, initializing the repository structure, and committing the generated artifacts.

Install the gh-aw CLI Extension

The first step adds the gh aw command set to your GitHub CLI. The installation script downloads the compiled binary into ~/.local/share/gh/extensions/gh-aw/.

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

Verify the installation succeeded by checking the version:

gh aw version

If the command returns a version string, the extension is ready. Ensure your base gh CLI is already installed and authenticated (gh auth status) before proceeding.

Initialize Your Repository for Agentic Workflows

Navigate to your repository root and run the initialization command. The --engine flag selects the default AI engine—copilot is the most common choice.

gh aw init --engine copilot

Generated Configuration Files

The init command creates a standardized directory structure and configuration files. According to the source analysis of github/gh-aw, the following artifacts are generated:

• .gitattributes – Marks *.lock.yml files as generated (linguist-generated=true merge=ours) to prevent merge conflicts.
• .github/aw/github-agentic-workflows.md – Human-readable documentation explaining the Agentic Workflows system.
• .github/agents/agentic-workflows.agent.md – The AI-agent prompt consumed by Copilot Chat to power the /agent experience.
• .vscode/settings.json & .vscode/mcp.json – VS Code configuration for MCP server access and safe-output handling.
• .github/workflows/copilot-setup-steps.yml – A minimal CI job that runs gh aw compile on every push to validate workflows.

These files form the backbone of a gh-aw-enabled repository. Manual edits are discouraged; use gh aw commands to keep the compiler and validation layers synchronized.

Commit and Push the Generated Files

Stage and commit the initialization artifacts to activate the workflow engine.

git status          # inspect the newly added files

git add .
git commit -m "Initialize repository for GitHub Agentic Workflows"
git push

If your repository has branch protection rules enabled, open a pull request instead of pushing directly to the default branch.

Verify Your Setup with a Sample Workflow

Test the installation by creating and compiling a sample workflow. The gh aw new command scaffolds a Markdown workflow definition, while gh aw compile generates the executable .lock.yml file that GitHub Actions runs.

gh aw new sample-workflow          # creates .github/workflows/sample-workflow.md + .lock.yml

gh aw compile sample-workflow       # regenerates the lock file from the Markdown source

The compilation logic resides in pkg/workflow/compiler.go within the github/gh-aw source tree. This compiler validates the natural-language steps and produces the secure, deterministic lock file required by the runtime.

Key Files and Their Roles

Understanding the repository layout helps when troubleshooting or extending gh-aw functionality.

Path	Purpose
install.md	Detailed installation and initialization instructions
create.md	Workflow creation, debugging, and upgrade cheat-sheet
install-gh-aw.sh	Bash installer script fetched during step 1
pkg/workflow/compiler.go	Core compiler that transforms Markdown into .lock.yml
actions/setup/README.md	Documentation for the GitHub Action that provisions runtime scripts
.github/workflows/copilot-setup-steps.yml	Generated CI job that validates workflows on push

Summary

• Install the gh aw CLI extension using the official install-gh-aw.sh script and verify with gh aw version.
• Initialize the repository with gh aw init --engine copilot to generate .gitattributes, VS Code settings, agent prompts, and starter workflows.
• Commit the generated files to activate the compiler and CI validation.
• Compile workflows using gh aw compile to generate the .lock.yml files that GitHub Actions executes.

Frequently Asked Questions

What is the minimum required GitHub CLI version for gh-aw?

The github/gh-aw extension requires the GitHub CLI to be installed and authenticated (gh auth status). While the repository does not specify a strict minimum version, you should use the latest stable gh release to ensure compatibility with the extension API and authentication scopes required for Copilot integration.

Can I use gh-aw with AI engines other than Copilot?

Yes. The gh aw init command accepts an --engine flag that supports multiple AI providers. While copilot is the default and most documented engine, the initialization logic in install.md indicates support for alternative engines such as Claude or custom endpoints. Check the specific engine documentation for required authentication tokens.

What does the .lock.yml file contain in gh-aw workflows?

The .lock.yml file is a compiled, deterministic representation of your natural-language Markdown workflow. According to pkg/workflow/compiler.go, this lock file contains the validated step definitions, resolved dependencies, and security constraints required by GitHub Actions. It is marked as generated in .gitattributes to prevent merge conflicts and ensure the runtime always uses the compiled version rather than the source Markdown.

How do I update the gh-aw CLI extension to the latest version?

Re-run the installation script to fetch the latest binary. Execute curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash again to download the updated release into ~/.local/share/gh/extensions/gh-aw/. Verify the update with gh aw version to confirm the new version string matches the latest release in the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}