GitHub Agentic Workflows

Create a GitHub Agentic Workflow

A GitHub Agentic Workflows (gh-aw) 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.

GitHub Web Interface

Section titled “GitHub Web Interface”

If you have access to GitHub Copilot, you can create and edit agentic workflows directly from the web interface. This asynchronous path can turn a prompt into a proposed workflow. For an interactive authoring session, use a coding agent as described in the next section.

Use one of these prompts in your repository.

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.
Create an agentic workflow from the GitHub web interface

Coding agent or VS Code

Section titled “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:

  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.

Choose the Right Step Lifecycle Hook

Section titled “Choose the Right Step Lifecycle Hook”

When you add deterministic setup or cleanup to a workflow, choose the smallest hook that matches the lifecycle point you need. See Custom Steps and Jobs for the canonical ordering guide, including the distinction between pre-checkout pre-steps: and the later pre-agent-steps: phase.

Initialize the Repository

Section titled “Initialize the Repository”

Running gh aw init is required to enable the authoring experience in the GitHub code agent. This step configures your repository so that you can create and modify agentic workflows directly from github.com or the GitHub mobile app, using the Copilot coding agent.

Terminal window
gh aw init

Alternatively, run this prompt in your coding agent:

Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md

This command:

  • Creates a dispatcher skill at .github/skills/agentic-workflows/SKILL.md, which registers the agentic-workflows skill in GitHub Copilot and enables workflow authoring with the agentic-workflows skill in Copilot Chat on github.com and the GitHub mobile app.
  • Sets up MCP server integration so that Copilot has access to gh-aw tools when creating or editing workflows.
  • Updates .gitattributes to mark generated .lock.yml files correctly.
  • Configures VS Code settings for the best local authoring experience.

Once initialized, you and your team can create and edit workflows by opening a Copilot Chat session on github.com or the GitHub app and running:

agentic-workflows Create a new workflow that...

Manual Editing

Section titled “Manual Editing”

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:

    Terminal window
    gh extension install github/gh-aw

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

    Terminal window
    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.

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

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

  5. If you haven’t done so already, configure authentication for the selected AI engine.

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.

Adding an Existing Workflow

Section titled “Adding an Existing Workflow”

To add a workflow from another repository, see Reusing Workflows.

Workshop

Section titled “Workshop”

Learn more

Section titled “Learn more”
Community Feedback
llms.txtllms-full.txtCreate WorkflowInstallReference

Made with by GitHub Next & Microsoft ResearchTermsPrivacySecurity