Create a GitHub Agentic Workflow

A GitHub Agentic Workflows source is a Markdown file in .github/workflows/ that describes AI-powered repository automation. YAML frontmatter configures triggers, permissions, tools, safe outputs, and the AI engine; the Markdown body contains natural-language instructions. The gh aw compile command turns this source into the .lock.yml GitHub Actions workflow that runs GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, or Pi.

Estimated time: 5-15 minutes depending on complexity

You can author new agentic workflows using a coding agent or other AI chat system, under your guidance. For interactive coding agents, this can be a conversation about what you want the workflow to do, with the agent asking clarifying questions and generating the workflow for you.

This guide shows how to create an agentic workflow in the GitHub web interface, with a coding agent, in VS Code Agent Mode, or by editing the source manually.

Create a New Workflow with the GitHub Web Interface

If you have access to GitHub Copilot, you can create and edit agentic workflows directly from the GitHub web interface. This can turn a prompt into a proposed workflow.

1. Use one of these prompts in the “Agents” tab in your repository.

Issue Triage

Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md

The purpose of the workflow is to triage new issues: label them by type and priority, identify duplicates, ask clarifying questions when the description is unclear, and assign them to the right team members.

Activity Report

Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md

The purpose of the workflow is a daily report on recent activity in the repository, delivered as an issue. The report should summarize new issues, pull requests merged, and any open blockers.

Documentation Updater

Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md

The purpose of the workflow is to run daily and keep the repository documentation up to date: identify doc files that are out of sync with recent code changes and open a pull request with the necessary updates.

AGENTS.md Maintainer

Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md

The purpose of the workflow is to run weekly and maintain the AGENTS.md file: review merged pull requests and updated source files since the last run, then open a pull request that keeps AGENTS.md accurate and current.

Repository Maintainer

Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md

The purpose of the workflow is to act as a repository maintainer: regularly inspect the repository for useful maintenance work, select one bounded task, and open a small draft pull request with the improvement and validation results.

Create an agentic workflow from the GitHub web interface

2. Set up required authentication.

   If you haven’t done so already, choose and authenticate an AI engine. Copilot is the default; set engine: in frontmatter for Claude Code, OpenAI Codex, Google Gemini, or Pi.

Create a New Workflow with a Coding Agent or VS Code

Follow these steps to create an agentic workflow using VS Code or a CLI coding agent.

1. Start your coding agent.

   Choose your preferred coding agent and start it in the context of your repository. For example, you can:

   • Start VSCode Agent Mode, or
   • Start your CLI coding agent in your repository, or
   • Start any chat system that can access your repository

2. Create an agentic workflow.

   Enter the following prompt into your coding agent:

   Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
   
   The purpose of the workflow is a daily report on recent activity in the repository, delivered as an issue.

   You can replace the last line with your desired workflow purpose and as much additional detail, context, goals, guardrails and purpose as you like.

   This will create a new workflow markdown file in .github/workflows/ with the appropriate configuration. Some agents will create a pull request to add these changes to your repository.

3. Set up required authentication.

   If you haven’t done so already, choose and authenticate an AI engine. Copilot is the default; set engine: in frontmatter for Claude Code, OpenAI Codex, Google Gemini, or Pi.

After merging the pull request, you can run the workflow to see it in action. Either:

• trigger runs manually from the Actions tab in GitHub.com, or
• use the gh aw run command to trigger runs from your terminal.

Create a New Workflow Manually

If you prefer to create workflows manually, you can

1. Create the workflow file in .github/workflows/<workflow-name>.md

2. Install the GitHub CLI and the GitHub Agentic Workflows extension:

   gh extension install github/gh-aw

3. Choose an engine and set up required authentication.

   Choose and authenticate an AI engine. Copilot is the default; set engine: in frontmatter for Claude Code, OpenAI Codex, Google Gemini, or Pi.

4. Compile the workflow markdown into a YAML workflow file using:

   gh aw compile

   This will generate a workflow YAML lock file .github/workflows/<workflow-name>.lock.yml based on the content of your markdown file.

5. Add, commit and push the workflow file and its lock file to your repository.

   git add .github/workflows/<workflow-name>.md
   git add .github/workflows/<workflow-name>.lock.yml
   git commit -m "Add <workflow-name> workflow"
   git push

You can now trigger runs of the workflow either from the Actions tab in GitHub.com or using the gh aw run command from your terminal.

Learn More

• Use Working with Workflows for additional authoring, editing, debugging, and upgrade techniques.
• Compare AI engines and authentication.
• Browse the GitHub Agentic Workflows gallery.
• Review the security architecture and FAQ.
• gh-aw-workshop.s