How to Run Coding Agents in CI with gh-aw and Aider

To run coding agents in continuous integration safely, compile declarative agent workflows with gh-aw for read-only repository tasks and invoke CLI runners like Aider for targeted code edits. This separation isolates untrusted reasoning steps from write access, preventing unauthorized repository changes while automating pull request reviews and patches directly within GitHub Actions.

Before you start

• A GitHub repository with GitHub Actions enabled.
• GitHub CLI (gh) v2.0.0 or later installed and authenticated with repo and workflow scopes.
• The gh-aw extension installed via gh extension install github/gh-aw.
• Model credentials stored in repository secrets, such as COPILOT_GITHUB_TOKEN or ANTHROPIC_API_KEY.

How CI agents execute safely

flowchart LR
  A[Pull request event] --> B[gh-aw compiles markdown intent]
  B --> C[Sandboxed read-only runner executes agent]
  C --> D{Does output meet safe-outputs policy?}
  D -- yes --> E[Separate job applies comments or edits]
  D -- no --> F[Write blocked by policy]

Step 1: Install the gh-aw extension

Authenticate your GitHub CLI session and install the extension:

gh auth login --scopes repo,workflow
gh extension install github/gh-aw

Step 2: Define the agentic workflow

Create .github/workflows/pr-review.md. This file combines YAML frontmatter for permissions and tools with Markdown for agent instructions:

---
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: read

engine: copilot

safe-outputs:
  add-comment:
    max: 1
  create-pull-request-review-comment:
    max: 10

tools:
  github:
    toolsets: [default]
---

# Pull Request Reviewer

Review the pull request diff for correctness, security, maintainability, and test coverage.

1. Analyze the code changes in the context of the repository.
2. Create inline review comments only for specific problems or concrete improvements.
3. Add one summary comment that groups findings by severity and notes anything that needs human follow-up.

Step 3: Compile the workflow lockfile

Generate the hardened, schema-validated GitHub Actions YAML lockfile from your Markdown file:

gh aw compile

This outputs .github/workflows/pr-review.lock.yml. Do not edit the .lock.yml file manually.

Step 4: Commit both files to the repository

Track both the source specification and the compiled lockfile in git:

git add .github/workflows/pr-review.md .github/workflows/pr-review.lock.yml
git commit -m "ci: add agentic pr reviewer workflow"
git push origin main

Step 5 (optional): Configure Aider for automated patch generation

To execute direct repository edits rather than read-only reviews, configure an in-process CLI runner using the Aider GitHub Action. Create .github/workflows/aider-fix.yml:

name: Aider Fix
on:
  issue_comment:
    types: [created]

jobs:
  aider:
    if: contains(github.event.comment.body, '/aider')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: mirrajabi/aider-github-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Common mistakes

• Editing the lockfile directly. Manual edits to .github/workflows/pr-review.lock.yml get overwritten on the next compile or cause drift. Update .github/workflows/pr-review.md and re-run gh aw compile.
• Committing without recompiling. Pushing changes to the .md file without running gh aw compile causes CI to run the previous version of the lockfile.
• Missing downstream triggers. Pull requests opened by an agent using the default GITHUB_TOKEN do not trigger downstream CI workflows. Store a personal access token in GH_AW_CI_TRIGGER_TOKEN to execute downstream suites.
• Granting write permissions to review agents. Assigning contents: write to unconstrained reasoning models risks unintended commits. Keep workflows read-only and restrict writes through safe-outputs.

Frequently asked questions

Why does gh-aw separate the markdown file from the lockfile?

The Markdown file defines developer intent, while the compiled .lock.yml file implements a secure, pinned GitHub Actions configuration. This architecture guarantees that engine boundaries, security permissions, and safe output validators remain reproducible across CI runs.

How do safe outputs protect CI workflows?

Safe outputs intercept model actions before they execute against the GitHub API. The workflow isolates write operations in a separate verification job, enforcing quotas on comments, labels, and pull requests to prevent spam or malicious repository writes.

When should you use gh-aw instead of Aider?

Use gh-aw for automated code reviews, issue triage, and policy checks where read-only execution and safe write barriers are necessary. Use Aider when a developer explicitly triggers automated code refactoring or patch creation on an existing branch.

Related

• Structuring repository constraints before running automation prevents agent drift; read Spec, Plan, Build, Review: A Workflow for Agent Coding.
• Automated CI gates prevent broken builds from reaching main; see Why AI agent checks Outperform Reminders in Mobile Dev.
• Review the official GitHub Agentic Workflows documentation and the GitHub changelog announcement for full syntax references.