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

> Easily set up gh-aw in a new repository with our guide. Install the CLI and initialize configuration files with simple commands for a smooth workflow.

- Repository: [GitHub/gh-aw](https://github.com/github/gh-aw)
- Tags: getting-started
- Published: 2026-02-16

---

**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/`.

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

```

Verify the installation succeeded by checking the version:

```bash
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.

```bash
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`](https://github.com/github/gh-aw/blob/main/.github/aw/github-agentic-workflows.md)** – Human-readable documentation explaining the Agentic Workflows system.
- **[`.github/agents/agentic-workflows.agent.md`](https://github.com/github/gh-aw/blob/main/.github/agents/agentic-workflows.agent.md)** – The AI-agent prompt consumed by Copilot Chat to power the `/agent` experience.
- **[`.vscode/settings.json`](https://github.com/github/gh-aw/blob/main/.vscode/settings.json) & [`.vscode/mcp.json`](https://github.com/github/gh-aw/blob/main/.vscode/mcp.json)** – VS Code configuration for MCP server access and safe-output handling.
- **[`.github/workflows/copilot-setup-steps.yml`](https://github.com/github/gh-aw/blob/main/.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.

```bash
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`](https://github.com/github/gh-aw/blob/main/.lock.yml) file that GitHub Actions runs.

```bash
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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/install.md) | Detailed installation and initialization instructions |
| [`create.md`](https://github.com/github/gh-aw/blob/main/create.md) | Workflow creation, debugging, and upgrade cheat-sheet |
| [`install-gh-aw.sh`](https://github.com/github/gh-aw/blob/main/install-gh-aw.sh) | Bash installer script fetched during step 1 |
| [`pkg/workflow/compiler.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/compiler.go) | Core compiler that transforms Markdown into [`.lock.yml`](https://github.com/github/gh-aw/blob/main/.lock.yml) |
| [`actions/setup/README.md`](https://github.com/github/gh-aw/blob/main/actions/setup/README.md) | Documentation for the GitHub Action that provisions runtime scripts |
| [`.github/workflows/copilot-setup-steps.yml`](https://github.com/github/gh-aw/blob/main/.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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/.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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/.lock.yml) file is a compiled, deterministic representation of your natural-language Markdown workflow. According to [`pkg/workflow/compiler.go`](https://github.com/github/gh-aw/blob/main/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.