Configuration Reference

Before creating agentic workflows, ensure you have the following:

What gh aw init Does

Running gh aw init in your repository:

# Initialize the repo
gh aw init --engine copilot

# Then manually create the required secret
gh secret set COPILOT_GITHUB_TOKEN -R owner/repo
# (paste your fine-grained PAT when prompted)

Every agentic workflow is a .md file in .github/workflows/ with two parts:

# File: .github/workflows/triage-issues.md
---
on:
  issues:
    types: [opened]
permissions: read-all
safe-outputs:
  add-labels:
    allowed: [bug, feature, docs]
  add-comment: {}
---

# Issue Triage Agent
Analyze new issues and apply the appropriate label.
Explain your reasoning in a comment.

Agentic workflows use repository secrets for authentication. The compiled .lock.yml workflow references these secrets at runtime during the activation and safe-outputs steps.

COPILOT_GITHUB_TOKEN — The Core Requirement

Every agentic workflow needs COPILOT_GITHUB_TOKEN — a fine-grained PAT from a user with an active Copilot license. The compiled workflow validates this secret during activation; without it, the run fails immediately.

gh secret set COPILOT_GITHUB_TOKEN -R owner/repo
# Paste your fine-grained PAT when prompted

Additional Secrets

Depending on your workflow configuration, you may need additional repository secrets:

Custom Tokens for Safe Outputs

By default, safe-output write operations use the built-in GITHUB_TOKEN. To use a different identity for writes (e.g., a bot account, a GitHub App), configure github-token: or github-app: in your safe-outputs.

safe-outputs:
  github-token:
    secret: MY_BOT_PAT
  create-pull-request:
    draft: true
  assign-to-agent:
    allowed: [copilot]

safe-outputs:
  github-app:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_KEY }}
  create-pull-request:
    draft: true
  add-comment: {}

PAT Required Scopes

Token Summary

The on: field uses standard GitHub Actions trigger syntax, extended with gh-aw-specific controls.

Standard Triggers

🕐 Fuzzy Schedule Syntax

Human-friendly schedules. The compiler assigns deterministic scattered times based on file path.

on:
  schedule: daily                              # Scattered daily
  schedule: daily around 14:00                 # ±1 hour of 14:00
  schedule: daily between 9:00 and 17:00       # Business hours
  schedule: weekly on friday around 5pm        # Weekly on Fridays
  schedule: hourly                             # Every hour
  schedule: every 10 minutes                   # Minimum 5 minutes

⚡ Slash & Label Commands

# Slash command — users type /review in comments
on:
  slash_command: "review"

# Label command — fires when label is added
on:
  label_command: "deploy"

🔧 gh-aw Trigger Extensions

# Shorthand
permissions: read-all

# Granular
permissions:
  contents: read
  issues: read
  pull-requests: read
  models: read        # Required for Copilot AI model access

engine: copilot

engine: claude

engine: codex

engine: gemini

Extended Engine Configuration

engine:
  id: copilot
  version: "0.0.422"            # Pin specific CLI version
  model: gpt-5                  # Override default model
  agent: technical-doc-writer   # Custom agent (.github/agents/<name>.agent.md)
  max-continuations: 3          # Autopilot mode (Copilot only)
  max-turns: 50                 # Max chat iterations (Claude only)
  env:
    DEBUG_MODE: "true"

GitHub Tool — Toolsets

tools:
  github:
    toolsets: [repos, issues, pull_requests, labels, code_search]
    read-only: true
    lockdown: true

Bash — Command Allowlisting

tools:
  bash:                              # Default safe commands only
  bash: true                         # All commands
  bash: ["echo", "git:*", "npm"]     # Specific commands

Complete Example

tools:
  edit:
  bash: ["gh", "git:*", "npm", "node"]
  github:
    toolsets: [issues, pull_requests, labels]
  web-fetch:
  web-search:
  cache-memory:
    key: "project-context"
  playwright:
  serena: ["typescript", "python"]
  timeout: 120

Safe outputs are the security boundary between read-only AI execution and write operations. The agent produces structured output; separate permission-controlled jobs execute the writes.

Issues & Discussions

Pull Requests

Labels, Assignments & Comments

Workflows & Security

Examples

safe-outputs:
  create-issue:
    title-prefix: "[ai] "
    labels: [automation, agentic]
    assignees: [copilot]
    max: 5
    expires: 7

  create-pull-request:
    title-prefix: "[ai] "
    draft: true
    reviewers: [copilot]
    auto-merge: true
    protected-files: "blocked"

  add-labels:
    allowed: [bug, enhancement, docs]
    max: 5

  add-comment:
    max: 3
    hide-older-comments: true

Three connection modes for external tools:

📡 Process (stdio)

mcp-servers:
  slack:
    command: "npx"
    args: ["-y", "@slack/mcp-server"]
    env:
      SLACK_BOT_TOKEN: "${{ secrets.SLACK_TOKEN }}"

🐳 Container (Docker)

mcp-servers:
  custom-db:
    container: "ghcr.io/org/db-mcp:latest"
    env:
      DATABASE_URL: "${{ secrets.DB_URL }}"

🌐 HTTP Endpoint

mcp-servers:
  remote-api:
    url: "https://api.example.com/mcp"
    headers:
      Authorization: "Bearer ${{ secrets.TOKEN }}"

Controlled by the Agent Workflow Firewall (AWF). Only whitelisted domains are accessible.

network: defaults                   # Basic infrastructure only

network:
  allowed:
    - defaults                      # Basic infra
    - python                        # PyPI ecosystem
    - node                          # NPM ecosystem
    - github                        # GitHub domains
    - "api.example.com"             # Custom domain
  blocked:
    - "cdn.tracker.com"             # Block specific (takes precedence)

Ecosystem Identifiers

Imports — Shared Configuration

imports:
  - "./shared/base-config.md"                          # Local file
  - "githubnext/agentics/shared/security.md@main"      # Remote

Concurrency

concurrency:
  group: "gh-aw-${{ github.workflow }}"
  cancel-in-progress: true

Custom Steps

steps:                             # Run BEFORE agent
  - uses: actions/setup-node@v4
    with:
      node-version: "20"

post-steps:                        # Run AFTER agent
  - run: echo "Agent completed"

Complete Workflow Example

---
name: "CI Failure Investigator"
description: "Investigates CI failures and proposes fixes"

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
  roles: [admin, maintainer]
  stop-after: "+90d"

permissions:
  contents: read
  actions: read
  issues: read

engine:
  id: copilot
  max-continuations: 3

tools:
  edit:
  bash: ["gh", "git:*", "npm"]
  github:
    toolsets: [repos, issues, pull_requests]

safe-outputs:
  create-pull-request:
    title-prefix: "[ci-fix] "
    labels: [ci-fix, automation]
    draft: true
  add-comment:
    max: 2

network:
  allowed:
    - defaults
    - node
    - github

timeout-minutes: 15
---

# CI Failure Investigator

When a CI workflow fails, investigate the failure:

1. Read the failed workflow logs
2. Identify the root cause
3. Search the codebase for the relevant code
4. Propose a fix as a pull request
5. Comment on the triggering issue with your analysis