My Experience with GitHub Agentic Workflows

If you’ve ever wished your CI/CD pipeline could think for itself, you’re going to like what comes next.

GitHub Next recently introduced a research project called Agentic Workflows – a way to embed autonomous AI agents directly into GitHub Actions.

These aren’t just scripted automation tasks; they can interpret natural language, reason about problems and adapt to context.

After experimenting with Agentic Workflows in my own repositories, I’ve decided to write a blog post about it. In this post, you’ll learn:

• What Agentic Workflows are and how they differ from traditional automation
• How to set them up in your repository step-by-step
• A real-world example where a workflow fixed a Terraform provider upgrade issue
• Best practices and security considerations
• Actionable next steps to start building your own AI-powered workflows

What are Github Agentic Workflows?

Traditional GitHub Actions are deterministic – you write YAML to define steps, and the runner executes exactly what you’ve defined. If you need to do something new, you edit the workflow and commit changes.

Agentic Workflows combine that deterministic structure with an AI-powered decision-making layer. Each workflow consists of:

• YAML frontmatter – defining triggers, permissions, and available tools
• Markdown instructions – plain language prompts telling the AI what to do

This dual structure means you can give high-level instructions like “Analyse failing CI checks, fix the code, and push changes”, and the AI determines the specific steps to achieve that – in context, while respecting the guardrails you’ve defined.

GitHub Next’s documentation calls this an “Actions-first” design. Your workflows still behave like standard GitHub Actions: they have triggers, permissions, logs, and security controls. The difference is that the execution logic is determined dynamically by an AI agent, not a rigid script.

Think of it as upgrading from a rigid recipe to a skilled sous-chef who understands why you’re doing something and can adapt on the fly.

Why I think this matters

From testing and reviewing GitHub’s documentation, the standout benefits are:

• Adaptive automation – No need to hard-code every possible branch or failure scenario. The AI can reason about your repository’s state.
• Multi-AI engine support – Use GitHub Copilot CLI, Anthropic Claude, or OpenAI Codex, depending on the task.
• Security-first design – Minimal default permissions, tool allowlists, and Safe Output Processing before execution.
• Rapid setup with pre-built templates – GitHub’s Agentics collection includes workflows for PR fixes, issue triage, weekly reports, and more.

Importantly, these workflows don’t replace GitHub Actions – they extend them. You can still use all your existing build/test/deploy logic, but now you can drop in AI-powered tasks where human-like reasoning adds value.

Prerequisites

Before you begin, ensure you have:

• A GitHub repository
• Maintainer access (to add secrets and workflows)
• API credentials for your chosen AI engine (Copilot CLI PAT, Claude API key, or Codex key)

Installing and Running Your First Agentic Workflow

Install GitHub CLI and Agentic Workflows Extension

First, install GitHub CLI:

brew install gh

Then install the Agentic Workflows extension:

gh extension install githubnext/gh-aw

If authentication fails, you may need to use a Personal Access Token. GitHub’s documentation provides an installation script as a fallback.

Add a Sample workflow

To see Agentic Workflows in action quickly, use one of the pre-built templates from the Agentics collection. Let’s try the PR Fix workflow – designed to automatically analyse and fix failing PR checks.

From your repository root:

gh aw add githubnext/agentics/pr-fix --pr

This creates a pull request adding two files:

• .github/workflows/pr-fix.md – source workflow with YAML + Markdown
• .github/workflows/pr-fix.lock.yml – compiled GitHub Actions workflow

The .md file is your source of truth; .lock.yml is the hardened, executable version.

Configure Your AI Engine

For Copilot CLI:

1. Go to GitHub’s token creation page
2. Add Copilot Requests permission
3. Generate the token
4. Store it in repository secrets:

gh secret set COPILOT_CLI_TOKEN -a actions --body "your-token-here"

If you use Claude or Codex, follow their respective setup instructions – the pattern is similar: create API key → add to secrets.

Understand the Workflow Structure

Open .github/workflows/pr-fix.md. You’ll see:

YAML frontmatter (wrapped in ---):

---
on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write

tools:
  github:
    toolset: [pull-requests, code]
---

This defines:

• Trigger: when someone comments on an issue or PR
• Permissions: minimal write access to contents and PRs
• Toolset: allows interaction with PR and code APIs

Markdown body – instructions to the AI (snippet example below, see full body here)

---
# PR Fix

You are an AI assistant specialized in fixing pull requests with failing CI checks. Your job is to analyze the failure logs, identify the root cause of the failure, and push a fix to the pull request branch for pull request #${{ github.event.issue.number }} in the repository ${{ github.repository }}.

This is the “thinking” part – the AI uses these instructions to plan and execute.

Trigger the Workflow

 in a PR with failing checks, comment:

/pr-fix

The AI will:

1. Analyse failure logs
2. Determine fixes
3. Commit changes
4. Comment with an explanation

Real-World Example: Terraform Provider Upgrade Fix

I was upgrading a Terraform provider from v1 to v2 – breaking changes everywhere. CI failed because body now expected an HCL object instead of a JSON-encoded string.

Instead of manually digging through documentation, I ran:

/pr-fix

The AI agent:

1. Read the CI logs
2. Found the provider’s migration guide entry about body
3. Updated my code to new syntax:

4. Ran terraform validate and terraform fmt
5. Pushed the changes back to the PR branch
6. Added a comment summary:

Minutes later, CI passed. Epic!

Security Considerations

According to the GitHub Agentic Workflows project page and the gh-aw documentation:

• Natural Language Workflow Definitions – Markdown replaces YAML as the authoring format
• CLI Compilation – The gh aw extension compiles .md into executable .yml
• Containerised Execution – AI agents run in isolated environments for reproducibility and safety
• Transparent Logs & Auditability – All runs are visible in standard Actions logs
• Security Controls – Read-only permissions by default, with write operations gated via safe-output processing

These workflows are still in prototype mode, so expect manual compilation and limited agent libraries for now. But the foundations are promising.

Tip: Start with read-only or minimal write permissions, then increase only if required.

Key Takeaways

GitHub Agentic Workflows represent a significant shift in how we can automate repository tasks. Instead of writing rigid automation scripts, we can describe what we want in natural language and let AI figure out the implementation details.

The combination of:

• Natural language instructions
• Secure, sandboxed execution
• Integration with familiar GitHub Actions infrastructure
• Flexibility to handle context-specific scenarios

…makes this a genuinely useful tool for development teams, not just a novelty.

I’m excited about what this means for:

• Continuous code quality improvements
• Intelligent issue triage
• Self-healing CI pipelines

And keep an eye on the Agentic Workflows page — new agents and templates are added regularly.

Start with something simple like the PR Fix workflow, see how it handles real scenarios in your codebase, and then expand from there.

Additional reading

• GitHub Agentic Workflows Project Page
• Quick Start Guide
• Workflow Structure Reference
• Agentics Collection

Have you tried GitHub Agentic Workflows in your projects? I’d love to hear about your use cases and experiences. Feel free to reach out or leave a comment below.