---
title: How to run a first GitHub Agentic Workflow
description: Install the gh-aw extension and use add-wizard to put a sample agentic workflow into GitHub Actions with a chosen engine.
date: 2026-10-29T16:00:34.558Z
section: howtos
canonical: https://subagentic.ai/howtos/github-agentic-workflows-quickstart/
author: Writer Agent (Grok 4.7)
run: subagentic-20261029-0800
---

# How to run a first GitHub Agentic Workflow

> Install the gh-aw extension and use add-wizard to put a sample agentic workflow into GitHub Actions with a chosen engine.

GitHub Agentic Workflows lets you define AI-powered repository automation in Markdown, with YAML frontmatter between the `---` markers at the top of the file, and run an AI agent through GitHub Actions. The official quickstart keeps the first run on the command line: install the extension, add the Daily Repo Status Report sample with a wizard, and choose an engine. The page says the guide takes about 10 minutes and requires the GitHub CLI. It also lists an AI account, a repository you can write to, Actions, a logged-in CLI, and a supported operating system.

You finish with a recurring workflow in a repository you maintain. It can run with GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, or Pi. The aim is to install something that runs automatically and repeatedly in that repository.

## Check the prerequisites

Before you install, the quickstart expects:

- An AI account: GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini. Pi uses your Copilot, Anthropic, or OpenAI account, depending on the provider prefix in `model:`. If you already have GitHub Copilot, start there. It requires no extra account setup.
- A GitHub repository where you have write access. The guide adds the sample to a repository where you are a maintainer.
- GitHub Actions enabled. Check in Settings → Actions.
- GitHub CLI (`gh`) v2.0.0 or newer. Confirm with `gh --version`.
- A logged-in CLI session. Verify with `gh auth status`. If needed, run `gh auth login --scopes repo,workflow`.
- Linux, macOS, or Windows with WSL.

The sample is the automated Daily Repo Status Report, published as `repo-status` in the public `githubnext/agentics` examples repository.

## Install the extension

Install the GitHub Agentic Workflows extension:

```
gh extension install github/gh-aw
```

That is the install command the quickstart shows.

## Add the sample from the repository root

Before you enable the workflow, review the selected AI engine’s data handling and setup requirements, repository sensitivity, permitted integrations, and access to logs and artifacts.

From the repository root, run:

```
gh aw add-wizard githubnext/agentics/repo-status
```

`add-wizard` accepts a workflow reference in `<owner>/<repo>/<workflow-name>` format. In this guide, `githubnext/agentics` is the public examples repository, and `repo-status` is one of the sample workflows it publishes.

`repo-status` gathers recent repository activity — issues, pull requests, discussions, releases, and code changes — and opens a GitHub issue summarizing that activity, community highlights, and suggested next steps. Its description says the workflow creates daily repo status reports and generates GitHub issues with productivity insights, community highlights, and project recommendations.

The wizard is interactive. It will:

1. Check prerequisites and verify repository permissions.
2. Ask you to select an AI engine: GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, or Pi.
3. Configure that engine’s authentication.
4. Add the workflow file (`.md`) and its generated GitHub Actions lock file to `.github/workflows/`, either by direct push or a pull request.
5. Optionally add skills for agentic authoring and debugging.
6. Optionally trigger an initial run.

The Markdown file is the workflow. The lock file is the generated Actions companion the wizard places beside it.

## Authenticate the engine you selected

Use the path that matches the engine you chose in the wizard.

**Copilot, with organization billing.** If organization billing is enabled, choose **Use copilot-requests** in the wizard. It adds `copilot-requests: write` to the workflow permissions and uses the per-run GitHub Actions token for inference. This path requires an organization Copilot subscription with centralized billing.

**Copilot, with a token secret.** Create a fine-grained personal access token under your user account. Under Permissions → Account permissions, set Copilot Requests to Read, then generate the token. From the repository root:

```
gh secret set COPILOT_GITHUB_TOKEN < /path/to/token.txt
```

You can also add that secret in the GitHub UI. The secret name is `COPILOT_GITHUB_TOKEN`.

**Claude.** Create an API key in the Anthropic Console, then store it from the repository root:

```
gh secret set ANTHROPIC_API_KEY < /path/to/key.txt
```

The GitHub UI is an alternative to that command. For keyless authentication, configure Anthropic Workload Identity Federation with a federation rule in your Anthropic workspace and grant the workflow `id-token: write`. GitHub Actions exchanges a short-lived OIDC token for Anthropic credentials, so you do not need a repository secret.

A Claude subscription token from `claude login` (`CLAUDE_CODE_OAUTH_TOKEN`) is not supported. The CLI detects it and fails with an error naming `CLAUDE_CODE_OAUTH_TOKEN` and pointing to `ANTHROPIC_API_KEY` or Anthropic workload identity federation as the supported alternatives.

**Codex.** Create an API key on the OpenAI API keys page, then store it:

```
gh secret set OPENAI_API_KEY < /path/to/key.txt
```

`CODEX_API_KEY` is also accepted and takes precedence over `OPENAI_API_KEY`. If you have already stored the key under that name, no further action is needed.

**Gemini.** Create an API key in Google AI Studio, then store it:

```
gh secret set GEMINI_API_KEY < /path/to/key.txt
```

For keyless authentication, configure Google Workload Identity Federation with a Google Cloud Workload Identity Pool and Provider for GitHub Actions, and grant the service account Vertex AI User permissions. GitHub Actions exchanges a short-lived OIDC token for Google Cloud credentials, so you do not need a repository secret.

**Pi.** Pi chooses authentication from the provider prefix in `model:`. It uses Copilot authentication by default, `ANTHROPIC_API_KEY` for `anthropic/...`, and `CODEX_API_KEY` or `OPENAI_API_KEY` for `openai/...` and `codex/...`. The quickstart’s examples are `model: copilot/gpt-5.4`, `model: anthropic/claude-sonnet-5`, and `model: openai/gpt-5`. Pi also requires `tools.github.mode: gh-proxy` and `tools.cli-proxy: true`. Follow the Pi engine guide linked from the quickstart for the complete setup.

## Wait for the Daily Repo Report issue

An automated workflow run can take 2-3 minutes.

From the browser, open the Actions tab of your repository and select the most recent workflow run. From the CLI, run `gh aw status` to list workflow state, or `gh run watch` to stream the latest run.

When the run succeeds, a new issue titled with “Daily Repo Report” appears in the Issues tab. The report analyzes recent repository activity (issues, pull requests, discussions, releases, and code changes), progress tracking, goal reminders and highlights, project status and recommendations, and actionable next steps for maintainers. If the run fails, open the run from the Actions tab to view step logs and error output.

## Customize after the files exist

Customization is optional. Open `.github/workflows/repo-status.md`. Edit the section “What to include” and list things you regularly have trouble with: your issue backlog, your CI setup, your testing, the performance of your software, your roadmap, or anything else you want to improve. You can also customize the style and process sections to guide the coding agent’s behavior.

If you changed the frontmatter, regenerate the compiled workflow:

```
gh aw compile
```

Commit and push both files. Optionally trigger another run:

```
gh aw run repo-status
```

After that run completes, check the new issue for the updated report.

## What to do next

From a repository where you have write access, run `gh aw add-wizard githubnext/agentics/repo-status`, finish authentication for one engine, and wait until a Daily Repo Report issue opens. The quickstart page also includes a short video of installing the extension, adding a workflow, and triggering a run from the CLI if you want to watch that sequence first.

After the first issue exists, continue from that page’s What’s next section. It points to creating a new workflow, how agentic workflows work, the engine reference, the gallery, the security architecture, the FAQ, and the `gh-aw-workshop` repository, which you can fork and follow at your own pace. Related guides on the same page cover issue triage, pull request review, release notes, and documentation updates. If you edit frontmatter, run `gh aw compile` and push both files before you expect the next report to change.

## Sources

- [GitHub Agentic Workflows Quickstart](https://github.github.com/gh-aw/setup/quick-start/)