GitHub Agentic Workflows

https://github.github.com/gh-aw
Admin
GitHub Agentic Workflows enable repository automation by running AI coding agents like Copilot,...
Tokens:481,338
Snippets:6,913
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup Runtime Tools

Source: https://github.github.com/gh-aw/reference/sandbox

Example of using setup actions to configure language runtimes that AWF captures and restores.

```yaml

---
jobs:
  setup:
    steps:
      - uses: actions/setup-go@v5
        with:
          go-version: '1.25'
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
---
```

--------------------------------

### Install Repo Assist Workflow

Source: https://github.github.com/gh-aw/examples/maintaining-repos

Use the interactive setup command to add the Repo Assist workflow to your repository.

```bash
gh aw add-wizard githubnext/agentics/repo-assist
```

--------------------------------

### Install CLI in GitHub Actions

Source: https://github.github.com/gh-aw/llms-full.txt

Use this setup step in a workflow file before running compilation commands.

```yaml
- uses: github/gh-aw/actions/setup-cli@<version>
- run: gh aw compile
```

--------------------------------

### GitHub Actions setup

Source: https://github.github.com/gh-aw/setup/cli

Install the extension within a GitHub Actions workflow using the setup-cli action.

```yaml
- name: Install gh-aw CLI
  uses: github/gh-aw/actions/setup-cli@main
  with:
    version: v0.37.18
```

--------------------------------

### Define Pre-Analysis Steps

Source: https://github.github.com/gh-aw/reference/threat-detection

Execute setup tasks such as authentication or tool installation before the AI engine runs.

```yaml
safe-outputs:
  create-pull-request:
  threat-detection:
    steps:
      - name: Connect to Security Gateway
        run: |
          echo "Setting up secure connection to analysis gateway..."
          # Authentication and connection setup
```

--------------------------------

### Dependabot Configuration Templates

Source: https://github.github.com/gh-aw/examples/multi-repo/dependabot-rollout

Example configurations for different repository types, ranging from simple setups to complex monorepos.

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"  # Low complexity = more frequent
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
```

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"  # High complexity = less frequent
    groups:
      production:
        patterns: ["*"]
        exclude-patterns: ["@types/*", "@jest/*"]
      dev-dependencies:
        patterns: ["@types/*", "@jest/*", "eslint*"]
```

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/packages/frontend"
    schedule:
      interval: "weekly"
  - package-ecosystem: "npm"
    directory: "/packages/backend"
    schedule:
      interval: "weekly"
```

--------------------------------

### Safe Outputs Configuration Examples

Source: https://github.github.com/gh-aw/specs/safe-outputs-specification

YAML configuration examples demonstrating type-specific allowlist overrides and same-repository restrictions.

```yaml

# Example 1: Type-specific allowlist (overrides global)
safe-outputs:
  allowed-github-references: [owner/repo-a, owner/repo-b]


  create-issue:
    allowed-repos: [owner/repo-c]  # Only repo-c permitted for issues


  add-comment:
    # No type-specific list, uses global: repo-a, repo-b


# Example 2: Explicit same-repository only
safe-outputs:
  create-issue:
    # No allowlist = same repository only
    max: 5

```

--------------------------------

### Configure GitHub App for Safe Outputs

Source: https://github.github.com/gh-aw/llms-full.txt

Example configuration for using GitHub App credentials to mint installation access tokens for safe output operations.

```yaml
safe-outputs:
  github-app:
    client-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
  create-issue:
```

--------------------------------

### Weighted Variant Setup

Source: https://github.github.com/gh-aw/experimental/experiments-specification

Example configuration for an experiment with three variants and non-uniform weights.

```yaml
experiments:
  storage: repo
  response_tone:
    variants: [formal, casual, neutral]
    weight: [20, 50, 30]
```

--------------------------------

### Example Model Alias Configuration

Source: https://github.github.com/gh-aw/specs/model-alias-specification

A practical example demonstrating alias overrides, custom aliases for specific tasks, and a default fallback policy.

```yaml
models:
  # Override the builtin sonnet alias to prefer a custom gateway
  sonnet:
    - mygateway/*sonnet-v3*
    - copilot/*sonnet*


  # New alias for high-effort reasoning tasks
  deep-think:
    - opus?effort=high
    - gpt-5?effort=high


  # Default policy: try deep-think first, fall back to sonnet
  "":
    - deep-think
    - sonnet
```

--------------------------------

### Complete MCP script workflow example

Source: https://github.github.com/gh-aw/reference/mcp-scripts

A full example demonstrating workflow triggers, script imports, tool definitions with inputs, and safe output categories.

```yaml
---
on: workflow_dispatch
engine: copilot
imports:
  - shared/pr-data-mcp-script.md
mcp-scripts:
  analyze-text:
    description: "Analyze text and return statistics"
    inputs:
      text:
        type: string
        required: true
    script: |
      const words = text.split(/\s+/).filter(w => w.length > 0);
      return {
        word_count: words.length,
        char_count: text.length,
        avg_word_length: (text.length / words.length).toFixed(2)
      };
safe-outputs:
  create-discussion:
    category: "General"
---
```

--------------------------------

### Day Boundary Handling Example

Source: https://github.github.com/gh-aw/specs/fuzzy-schedule-specification

Example calculation demonstrating how to handle day wrapping when the conversion results in a negative time value.

```text
local_time = 02:00 (2 AM)
offset = +9 hours
UTC_time = 02:00 - 9:00 = -7:00 → 17:00 (previous day)
```

--------------------------------

### Start MCP Gateway

Source: https://github.github.com/gh-aw/editor

Configures and starts the MCP Gateway container with necessary environment variables and volume mounts.

```bash
set -eo pipefail
mkdir -p "${RUNNER_TEMP}/gh-aw/mcp-config"
if [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -r "${GITHUB_EVENT_PATH}" ]; then
  GH_AW_SAFEOUTPUTS_EVENT_PATH="${RUNNER_TEMP}/gh-aw/safeoutputs/github_event.json"
  cp "${GITHUB_EVENT_PATH}" "${GH_AW_SAFEOUTPUTS_EVENT_PATH}"
  export GITHUB_EVENT_PATH="${GH_AW_SAFEOUTPUTS_EVENT_PATH}"
fi

# Export gateway environment variables for MCP config and gateway script
export MCP_GATEWAY_PORT="8080"
export MCP_GATEWAY_DOMAIN="awmg-mcpg"
export MCP_GATEWAY_HOST_DOMAIN="localhost"
MCP_GATEWAY_API_KEY=$(openssl rand -base64 45 | tr -d '/+=')
echo "::add-mask::${MCP_GATEWAY_API_KEY}"
export MCP_GATEWAY_API_KEY
export MCP_GATEWAY_PAYLOAD_DIR="/tmp/gh-aw/mcp-payloads"
mkdir -p "${MCP_GATEWAY_PAYLOAD_DIR}"
export MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD="524288"
export MCP_GATEWAY_ALLOWED_MOUNT_ROOTS="${GITHUB_WORKSPACE}:rw,${RUNNER_TEMP}/gh-aw:ro,${RUNNER_TEMP}/gh-aw/safeoutputs:rw,/opt:ro,/tmp:rw,/usr/bin/gh:ro"
export DEBUG="*"

export GH_AW_ENGINE="copilot"
MCP_GATEWAY_UID=$(id -u 2>/dev/null || echo '0')
MCP_GATEWAY_GID=$(id -g 2>/dev/null || echo '0')
source "${RUNNER_TEMP}/gh-aw/actions/resolve_docker_socket_gid.sh"
export MCP_GATEWAY_DOCKER_COMMAND='docker run -i --rm --network bridge -p 127.0.0.1:'"${MCP_GATEWAY_PORT}"':'"${MCP_GATEWAY_PORT}"' --name awmg-mcpg --add-host host.docker.internal:host-gateway --user '"${MCP_GATEWAY_UID}"':'"${MCP_GATEWAY_GID}"' --group-add '"${DOCKER_SOCK_GID}"' -v '"${DOCKER_SOCK_PATH}"':/var/run/docker.sock -e MCP_GATEWAY_PORT -e MCP_GATEWAY_DOMAIN -e MCP_GATEWAY_API_KEY -e MCP_GATEWAY_PAYLOAD_DIR -e MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD -e DOCKER_HOST=unix:///var/run/docker.sock -e DEBUG -e MCP_GATEWAY_LOG_DIR -e GH_AW_MCP_LOG_DIR -e GH_AW_SAFE_OUTPUTS -e GH_AW_SAFE_OUTPUTS_CONFIG_PATH -e GH_AW_SAFE_OUTPUTS_TOOLS_PATH -e GH_AW_POLICY_ALLOW_CREATE_PULL_REQUEST -e GH_AW_ASSETS_BRANCH -e GH_AW_ASSETS_MAX_SIZE_KB -e GH_AW_ASSETS_ALLOWED_EXTS -e DEFAULT_BRANCH -e GITHUB_MCP_SERVER_TOKEN -e GITHUB_MCP_GUARD_MIN_INTEGRITY -e GITHUB_MCP_GUARD_REPOS -e GH_AW_SINK_VISIBILITY -e GITHUB_REPOSITORY -e GITHUB_SERVER_URL -e GITHUB_SHA -e GITHUB_WORKSPACE -e GITHUB_TOKEN -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RUN_ATTEMPT -e GITHUB_JOB -e GITHUB_ACTION -e GITHUB_EVENT_NAME -e GITHUB_EVENT_PATH -e GITHUB_ACTOR -e GITHUB_ACTOR_ID -e GITHUB_TRIGGERING_ACTOR -e GITHUB_WORKFLOW -e GITHUB_WORKFLOW_REF -e GITHUB_WORKFLOW_SHA -e GITHUB_REF -e GITHUB_REF_NAME -e GITHUB_REF_TYPE -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e RUNNER_TEMP -e RUNNER_TOOL_CACHE -e MCP_GATEWAY_ALLOWED_MOUNT_ROOTS -v /tmp/gh-aw/mcp-payloads:/tmp/gh-aw/mcp-payloads:rw -v /opt:/opt:ro -v /tmp:/tmp:rw -v '"${GITHUB_WORKSPACE}"':'"${GITHUB_WORKSPACE}"':rw -v '"${RUNNER_TEMP}"'/gh-aw/safeoutputs:'"${RUNNER_TEMP}"'/gh-aw/safeoutputs:rw ghcr.io/github/gh-aw-mcpg:v0.4.10'
```

--------------------------------

### Configure Max Turns (Example)

Source: https://github.github.com/gh-aw/reference/glossary

Example of setting the maximum number of chat iterations.

```yaml
max-turns: 20
```

--------------------------------

### Start the MCP Server

Source: https://github.github.com/gh-aw/reference/gh-aw-as-mcp-server

Run the server directly from the command line.

```bash
gh aw mcp-server
```

--------------------------------

### Install a complete workflow

Source: https://github.github.com/gh-aw/practices/sharing-workflows

Use the CLI to pull a workflow from a remote repository into the current project.

```bash
gh aw add acme-org/agentic-workflows/ci-doctor@v1.2.0
```

--------------------------------

### Script Execution Examples

Source: https://github.github.com/gh-aw/schemas/mcp-scripts-config.schema.json

Various examples of script definitions including JavaScript, shell commands, Python, and Go.

```json
{
      "greet-user": {
        "description": "Greet a user by name",
        "inputs": {
          "name": {
            "type": "string",
            "required": true,
            "description": "Name of the user to greet"
          }
        },
        "script": "return { message: `Hello, ${name}!` };"
      }
    }
```

```json
{
      "list-prs": {
        "description": "List pull requests using gh CLI",
        "inputs": {
          "repo": {
            "type": "string",
            "required": true,
            "description": "Repository in owner/name format"
          },
          "state": {
            "type": "string",
            "default": "open",
            "enum": ["open", "closed", "all"],
            "description": "PR state filter"
          }
        },
        "run": "gh pr list --repo \"$INPUT_REPO\" --state \"$INPUT_STATE\" --json number,title",
        "env": {
          "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
        },
        "timeout": 30
      }
    }
```

```json
{
      "analyze-data": {
        "description": "Analyze numeric data with Python",
        "inputs": {
          "numbers": {
            "type": "string",
            "description": "Comma-separated numbers",
            "required": true
          }
        },
        "py": "import json\n\nnumbers_str = inputs.get('numbers', '')\nnumbers = [float(x.strip()) for x in numbers_str.split(',') if x.strip()]\n\nresult = {\n    \"count\": len(numbers),\n    \"sum\": sum(numbers),\n    \"average\": sum(numbers) / len(numbers) if numbers else 0\n}\n\nprint(json.dumps(result))",
        "timeout": 60
      }
    }
```

```json
{
      "calculate": {
        "description": "Perform calculations with Go",
        "inputs": {
          "a": {
            "type": "number",
            "required": true
          },
          "b": {
            "type": "number",
            "required": true
          }
        },
        "go": "a := inputs[\"a\"].(float64)\nb := inputs[\"b\"].(float64)\nresult := map[string]any{\n    \"sum\": a + b,\n    \"product\": a * b,\n}\njson.NewEncoder(os.Stdout).Encode(result)",
        "timeout": 30
      }
    }
```

```json
{
      "fetch-api-data": {
        "description": "Fetch data from external API with authentication",
        "inputs": {
          "endpoint": {
            "type": "string",
            "required": true,
            "description": "API endpoint path"
          },
          "method": {
            "type": "string",
            "default": "GET",
            "enum": ["GET", "POST", "PUT", "DELETE"]
          }
        },
        "script": "const apiKey = process.env.API_KEY;\nconst response = await fetch(`https://api.example.com/${endpoint}`, {\n  method,\n  headers: { 'Authorization': `Bearer ${apiKey}` }\n});\nreturn await response.json();",
        "env": {
          "API_KEY": "${{ secrets.SERVICE_API_KEY }}"
        }
      }
    }
```

```json
{
      "fetch-with-requests": {
        "description": "Fetch URL with Python requests library",
        "inputs": {
          "url": {
            "type": "string",
            "required": true,
            "description": "URL to fetch"
          }
        },
        "py": "import requests\nimport json\nresponse = requests.get(inputs.get('url'))\nprint(json.dumps({'status': response.status_code, 'length': len(response.text)}))",
        "dependencies": ["requests"],
        "timeout": 60
      }
    }
```

--------------------------------

### Worked Example Output Summary

Source: https://github.github.com/gh-aw/specs/effective-tokens-specification

Final aggregated output summary for the worked example, showing total invocations and calculated token metrics.

```json
{
  "summary": {
    "total_invocations": 3,
    "raw_total_tokens": 1800,
    "base_weighted_tokens": 2730,
    "effective_tokens": 4760
  }
}
```

--------------------------------

### Worked Example Computation Steps

Source: https://github.github.com/gh-aw/specs/effective-tokens-specification

Step-by-step breakdown of the Effective Token (ET) calculation for each invocation in the worked example.

```text
root:
  base = (1.0 × max(500-200,0)) + (0.1 × 200) + (4.0 × 150) = 300 + 20 + 600 = 920
  ET   = 2.0 × 920 = 1840


retrieval:
  base = (1.0 × 300) + (4.0 × 100) = 300 + 400 = 700
  ET   = 1.0 × 700 = 700


synthesis:
  base = (1.0 × max(200-100,0)) + (0.1 × 100) + (4.0 × 250) = 100 + 10 + 1000 = 1110
  ET   = 2.0 × 1110 = 2220
```

--------------------------------

### Environment Variable Configuration Example

Source: https://github.github.com/gh-aw/reference/mcp-gateway

Example of using an environment variable reference within an MCP server configuration block.

```json
{
  "mcpServers": {
    "github": {
      "container": "ghcr.io/github/github-mcp-server:latest",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}
```

--------------------------------

### C++ Repository 30-Minute Timeout Example

Source: https://github.github.com/gh-aw/reference/sandbox

Example configuration for a C++ repository using a 30-minute agent budget and a 5-minute per-tool-call limit.

```yaml

---
on:
  issues:
    types: [opened, labeled]


engine: copilot


runs-on: [self-hosted, linux, x64, large]   # fast self-hosted runner
timeout-minutes: 30                          # 30-minute agent budget


tools:
  bash: [":*"]
  timeout: 300                               # 5-minute per-tool-call budget


network:
  allowed:
    - defaults
    - go
    - node
---


Reproduce the bug described in this issue, add a regression test, and fix it.
Build with `cmake --build build -j$(nproc)` and verify with `ctest --output-on-failure`.

```

--------------------------------

### Scheduled repository report workflow example

Source: https://github.github.com/gh-aw/engines/claude

A complete workflow example for generating a daily repository status report using the Claude engine.

```yaml

---
on:
  schedule: daily


permissions:
  contents: read
  issues: read
  pull-requests: read


engine: claude


safe-outputs:
  create-issue:
    title-prefix: "[status] "
    labels: [report]
    close-older-issues: true
---


# Daily Repository Status


Analyze the repository and create a concise daily status report covering:
- Open issues and their priority
- Recent PR activity
- Upcoming work items

```

--------------------------------

### Configure Custom Language Server

Source: https://github.github.com/gh-aw/llms-full.txt

Includes a manual installation step for language servers that are not built-in.

```yaml
engine:
  id: copilot

steps:
  - name: Install custom language server
    run: npm install -g my-custom-language-server

lsp:
  mylang:
    command: my-custom-language-server
    args: ["--stdio"]
    fileExtensions:
      ".ml": mylang
```

--------------------------------

### Configure Server with Volume Mounts and Custom Entrypoint

Source: https://github.github.com/gh-aw/reference/mcp-gateway

Demonstrates mounting host directories into the container and specifying a custom entrypoint script.

```json
{
  "mcpServers": {
    "data-server": {
      "container": "ghcr.io/example/data-mcp:latest",
      "entrypoint": "/custom/entrypoint.sh",
      "entrypointArgs": ["--config", "/app/config.json"],
      "mounts": [
        "/host/data:/container/data:ro",
        "/host/config:/container/config:rw"
      ],
      "type": "stdio"
    }
  },
  "gateway": {
    "port": 8080,
    "domain": "localhost",
    "apiKey": "gateway-secret-token"
  }
}
```

--------------------------------

### Run add-wizard with various inputs

Source: https://github.github.com/gh-aw/setup/cli

Examples of using the add-wizard command with different workflow sources and configuration flags.

```bash
gh aw add-wizard githubnext/agentics/ci-doctor           # Interactive setup
gh aw add-wizard https://github.com/org/repo/blob/main/workflows/my-workflow.md
gh aw add-wizard https://example.com/workflows/my-workflow.json   # Arbitrary URL (JSON workflow)
gh aw add-wizard githubnext/agentics/ci-doctor --no-secret  # Skip secret prompt
```

--------------------------------

### Import copilot-setup-steps.yml

Source: https://github.github.com/gh-aw/llms-full.txt

Importing copilot-setup-steps.yml extracts only the steps from the copilot-setup-steps job and places them at the start of the agent job.

```yaml
---
on: issue_comment
engine: copilot
imports:
  - copilot-setup-steps.yml
  - shared/common-tools.md
steps:
  - name: Custom environment setup
    run: echo "Main frontmatter step runs last"
---
```

--------------------------------

### Define Pre-Agent Steps

Source: https://github.github.com/gh-aw/reference/steps-jobs

Use pre-agent steps for prerequisite MCP installation or configuration before the gateway starts.

```yaml
pre-agent-steps:
  - name: Finalize Context
    run: ./scripts/prepare-agent-context.sh
```

--------------------------------

### Define Custom Job Lifecycle Steps

Source: https://github.github.com/gh-aw/llms-full.txt

Use setup-steps for early credential bootstrapping and pre-steps for tasks running after framework scaffolding but before main steps.

```yaml
jobs:
  custom-job:
    runs-on: ubuntu-latest
    setup-steps:
      - name: Bootstrap credentials
        run: echo "runs before framework token/checkout setup"
    pre-steps:
      - name: Pre-flight setup
        run: echo "runs before checkout"
    steps:
      - name: Custom step
        run: echo "Custom job"
```

--------------------------------

### Examples of adding workflows via wizard

Source: https://github.github.com/gh-aw/guides/reusing-workflows

Demonstrates various ways to invoke the add-wizard command, including full URLs, short forms, and skipping secret prompts.

```bash
# Full GitHub URL
gh aw add-wizard https://github.com/githubnext/agentics/blob/main/workflows/daily-repo-status.md


# Short form (for workflows in top-level workflows/ directory)
gh aw add-wizard githubnext/agentics/daily-repo-status


# Skip the API key prompt when a secret is already configured
gh aw add-wizard githubnext/agentics/daily-repo-status --no-secret
```

--------------------------------

### Standalone installation

Source: https://github.github.com/gh-aw/setup/cli

Use shell or PowerShell scripts to install the extension if the standard CLI installation fails.

```bash
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash                # Latest
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s v0.1.0      # Pinned
```

```powershell
Invoke-WebRequest https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.ps1 -OutFile install-gh-aw.ps1; pwsh -File ./install-gh-aw.ps1          # Latest
Invoke-WebRequest https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.ps1 -OutFile install-gh-aw.ps1; pwsh -File ./install-gh-aw.ps1 v0.1.0  # Pinned
```

--------------------------------

### Initialize Trial Mode

Source: https://github.github.com/gh-aw/experimental/trial-ops

Executes a workflow in a temporary private repository to capture outputs safely.

```bash
gh aw trial githubnext/agentics/weekly-research
```

--------------------------------

### Install gh-aw via standalone script

Source: https://github.github.com/gh-aw/troubleshooting/common-issues

Use these commands to install the extension directly or pin a specific version when standard installation fails.

```bash
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s -- v0.40.0
```

--------------------------------

### Deduplication workflow example

Source: https://github.github.com/gh-aw/llms-full.txt

Example workflow configuration for processing issues with deduplication.

```markdown
---
on:
  schedule:
    - cron: "0 9 * * *"
permissions:
  issues: read
engine: copilot
tools:
  github:
    toolsets: [issues]
  cache-memory: true
safe-outputs:
  create-issue:
    title-prefix: "[daily-digest] "
    close-older-issues: true
    labels: [automation]
timeout-minutes: 15
---

Fetch the 20 most recently updated open issues.

Load `/tmp/gh-aw/cache-memory/processed.json` if it exists; it contains issue numbers from past digests. Skip any whose number already appears.

Summarize remaining (new) issues. If none, use the `noop` safe output.

Before finishing, write the updated processed-issue list back to `/tmp/gh-aw/cache-memory/processed.json` using filesystem-safe timestamp `YYYY-MM-DD-HH-MM-SS` (no colons, no `T`, no `Z`).
```

--------------------------------

### Initialize Runtime Server

Source: https://github.github.com/gh-aw/specs/safe-outputs-specification

Load configuration and register tools with the MCP server.

```javascript
const config = JSON.parse(fs.readFileSync('/opt/gh-aw/safeoutputs/config.json'));
const tools = config.tools;
const handlers = config.handlers;


for (const [name, schema] of Object.entries(tools)) {
  registerTool(server, name, schema, createHandler(handlers[name]));
}
```

--------------------------------

### Unaligned Bar Chart Example

Source: https://github.github.com/gh-aw/llms-full.txt

An example of poor alignment practices to avoid.

```text
API ███████
Worker ████
Cache █████████
```

--------------------------------

### Configure an MCP tool with parameters and environment variables

Source: https://github.github.com/gh-aw/reference/mcp-scripts

Demonstrates the full configuration schema including input parameters, environment variable mapping, and execution timeouts.

```yaml
mcp-scripts:
  tool-name:
    description: "What the tool does"  # Required
    inputs:                            # Optional parameters
      param1:
        type: string
        required: true
        description: "Parameter description"
      param2:
        type: number
        default: 10
    script: |                          # JavaScript implementation
      // Your code here
    env:                               # Environment variables
      API_KEY: "${{ secrets.API_KEY }}"
    timeout: 120                       # Optional: timeout in seconds (default: 60)
```

--------------------------------

### Update installed workflows

Source: https://github.github.com/gh-aw/practices/sharing-workflows

Refresh installed workflows to pull the latest changes from their source.

```bash
gh aw update ci-doctor          # update one workflow
gh aw update                    # update all tracked workflows
```

--------------------------------

### Install the extension via curl script

Source: https://github.github.com/gh-aw/setup/quick-start

Alternative installation method for troubleshooting authentication issues.

```bash
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
```

--------------------------------

### Reference Project Tokens in Workflow

Source: https://github.github.com/gh-aw/reference/auth-projects

Configuration example showing how to apply read and write tokens to specific tools and safe outputs.

```yaml
tools:
  github:
    mode: remote
    toolsets: [projects]
    github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }}


safe-outputs:
  update-project:
    project-url: https://github.com/orgs/my-org/projects/1
    github-token: ${{ secrets.GH_AW_WRITE_PROJECT_TOKEN }}
```

--------------------------------

### Timezone Conversion Examples

Source: https://github.github.com/gh-aw/specs/fuzzy-schedule-specification

Examples of converting local time schedules to UTC-based fuzzy expressions.

```yaml
# JST (UTC+9) business hours to UTC
schedule: daily between 9am utc+9 and 5pm utc+9
# Converts to: daily between 0:00 and 8:00 (UTC)
# Fuzzy: FUZZY:DAILY_BETWEEN:0:0:8:0 * * *


# EST (UTC-5) afternoon meeting
schedule: weekly on monday around 3pm utc-5
# Converts to: weekly on monday around 20:00 (UTC)
# Fuzzy: FUZZY:WEEKLY:1:AROUND:20:0 * * 1


# IST (UTC+5:30) morning standup
schedule: daily around 9:30am utc+05:30
# Converts to: daily around 4:00 (UTC)
# Fuzzy: FUZZY:DAILY_AROUND:4:0 * * *
```

--------------------------------

### Example Integrity-Scoped Cache Keys

Source: https://github.github.com/gh-aw/specs/safe-outputs-specification

Examples of cache keys generated under different guard policy configurations.

```text
# Default cache, with guard policy (min-integrity: unapproved, 8-char policy hash)
memory-unapproved-7e4d9f12-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }}


# Default cache, no guard policy
memory-none-nopolicy-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }}


# Named "session" cache, no guard policy
memory-none-nopolicy-session-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }}
```

--------------------------------

### Full Experiment Configuration Example

Source: https://github.github.com/gh-aw/experimental/experiments-specification

A complete YAML configuration for an experiment, including metadata, variant definitions, metrics, and conditional prompt logic.

```yaml
---
on:
  schedule: daily on weekdays
engine: copilot
permissions:
  contents: read
  pull-requests: read


experiments:
  storage: repo
  prompt_style:
    variants: [concise, detailed, step_by_step]
    description: "Test whether verbosity level affects output quality"
    hypothesis: "H0: no change in aic. H1: concise reduces by >=15%"
    metric: aic
    secondary_metrics: [duration_ms, discussion_word_count]
    guardrail_metrics:
      - name: success_rate
        threshold: ">=0.95"
      - name: empty_output_rate
        direction: min
        threshold: 0.0
    weight: [40, 40, 20]
    min_samples: 30
    start_date: "2026-05-01"
    end_date: "2026-08-01"
    issue: 1234
    analysis_type: t_test
    tags: [cost, prompting, verbosity]
    notify:
      issue: 1234
---


Summarize the pull requests merged today.


{{#if experiments.prompt_style == "concise" }}
Write a maximum of 5 bullet points.
{{#else if experiments.prompt_style == "detailed" }}
Write a structured report with sections for new features, bug fixes, refactors, and docs.
{{#else}}
Write a numbered step-by-step walkthrough of each change with rationale.
{{#endif}}
```

--------------------------------

### Install GitHub Agentic Workflows extension

Source: https://github.github.com/gh-aw/setup/creating-workflows

Installs the required extension for the GitHub CLI to manage agentic workflows.

```bash
gh extension install github/gh-aw
```

--------------------------------

### Error Code Reference Examples

Source: https://github.github.com/gh-aw/specs/fuzzy-schedule-specification

Examples of invalid syntax and time formats that trigger specific error codes.

```text
monthly
25:00
mondey
daily around
daily at 14:00
25
60
13pm
utc+25
utc9
every 0h
every 5h
Two schedule: expressions in one workflow scope
```

--------------------------------

### Configure Containerized MCP Server

Source: https://github.github.com/gh-aw/schemas/mcp-gateway-config.schema.json

Sets up a containerized MCP server with custom entrypoints, volume mounts, and specific startup/tool timeouts.

```json
    {
      "mcpServers": {
        "data-server": {
          "container": "ghcr.io/example/data-mcp:latest",
          "entrypoint": "/custom/entrypoint.sh",
          "entrypointArgs": ["--config", "/app/config.json"],
          "mounts": ["/host/data:/container/data:ro", "/host/config:/container/config:rw"],
          "type": "stdio"
        }
      },
      "gateway": {
        "port": 8080,
        "domain": "localhost",
        "startupTimeout": 60,
        "toolTimeout": 120
      }
    }
```

--------------------------------

### Peak Minutes Avoidance Logic Examples

Source: https://github.github.com/gh-aw/specs/fuzzy-schedule-specification

Examples demonstrating the application of avoidHourBoundary and avoidPeakMinutes to raw scattered times.

```text
FUZZY:DAILY_AROUND:14:00, workflow "my-scanner"
  Raw scattered time: 14:28
  Step 1 (avoidHourBoundary): 28 → 28  (no change; 28 ∈ [5,54])
  Step 2 (avoidPeakMinutes):  28 → 34  (shifted; hour ∈ [14,18], minute 28 ∈ [27,33]
                                          — wait, hour=14, so EU rule doesn't apply;
                                          US :15 rule: 28 ∉ [12,18]; :45 rule: 28 ∉ [42,48])
  → no shift needed; result: 14:28


FUZZY:DAILY_AROUND:15:00, workflow "my-monitor"
  Raw scattered time: 15:13
  Step 1 (avoidHourBoundary): 13 → 13  (no change)
  Step 2 (avoidPeakMinutes):  13 → 19  (shifted; hour ∈ [14,18], minute 13 ∈ [12,18])
  → result: 15:19
```

--------------------------------

### Timezone Conversion Example

Source: https://github.github.com/gh-aw/specs/fuzzy-schedule-specification

Example calculation for converting local time to UTC time using a specific offset.

```text
local_time = 14:00 (2 PM)
offset = +9 hours (JST)
UTC_time = 14:00 - 9:00 = 05:00 (5 AM UTC)
```

--------------------------------

### Example Configuration for Safe Outputs

Source: https://github.github.com/gh-aw/specs/safe-outputs-specification

Demonstrates the YAML structure for configuring the GitHub App and comment settings, including the opt-in for discussion permissions.

```yaml

safe-outputs:
  github-app:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
    owner: 'myorg'
    repositories: ['myrepo']
  add-comment:
    target: "*"
    max: 1
    discussions: true   # Opt in to discussions:write permission

```

--------------------------------

### Initialize GitHub Copilot Agent

Source: https://github.github.com/gh-aw/reference/gh-aw-as-mcp-server

Set up the environment for GitHub Copilot Agent, including MCP server integration.

```bash
gh aw init
```

--------------------------------

### Setup Scripts Action

Source: https://github.github.com/gh-aw/editor

Configures the environment for custom scripts using the local actions/setup action.

```yaml
- name: Setup Scripts
  id: setup
  uses: ./actions/setup
  with:
    destination: ${{ runner.temp }}/gh-aw/actions
    job-name: ${{ github.job }}
  env:
    GH_AW_SETUP_WORKFLOW_NAME: "hello-world"
    GH_AW_CURRENT_WORKFLOW_REF: ${{ github.repository }}/.github/workflows/workflow.lock.yml@${{ github.ref }}
    GH_AW_INFO_VERSION: "1.0.80"
    GH_AW_INFO_AWF_VERSION: "v0.28.7"
    GH_AW_INFO_ENGINE_ID: "copilot"
```

--------------------------------

### Hint Strategy Implementation Example

Source: https://github.github.com/gh-aw/llms-full.txt

A GitHub Actions workflow configuration demonstrating the Hint strategy for issue triage.

```markdown
---
on:
  issues:
    types: [opened]
engine: copilot
tools:
  github:
    toolsets: [issues]
permissions:
  issues: write
---

Triage the newly opened issue.

If there are relevant skills under `skills/` or `.github/skills/`, read them and
apply their guidance. Focus on skills related to issue classification or project
conventions.
```

--------------------------------

### Conditional Markdown Example

Source: https://github.github.com/gh-aw/reference/templating

Example of using conditional blocks to display content based on GitHub event data.

```yaml

---
on:
  issues:
    types: [opened]
---


# Issue Analysis


Analyze issue #${{ github.event.issue.number }}.


{{#if github.event.issue.number}}
## Issue-Specific Analysis
You are analyzing issue #${{ github.event.issue.number }}.
{{/if}}


{{#if github.event.pull_request.number}}
## Pull Request Analysis
You are analyzing PR #${{ github.event.pull_request.number }}.
{{/if}}

```

--------------------------------

### Initialize Repository for Agentic Workflows

Source: https://github.github.com/gh-aw/guides/agentic-authoring

Commands to set up a repository for GitHub Agentic Workflows.

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

```bash
gh aw init
```

--------------------------------

### Install gh-aw via Shell Script

Source: https://github.github.com/gh-aw/reference/releases

Use the installation script to fetch the latest version or a specific release tag.

```bash
# Latest (default — no version flag needed)
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash


# Specific version
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s v0.64.5
```

--------------------------------

### Initialize Side Repository

Source: https://github.github.com/gh-aw/examples/multi-repo/code-quality-monitoring

Commands to create and clone the repository used for hosting the automation workflow.

```bash
gh repo create my-org/main-repo-quality --private
gh repo clone my-org/main-repo-quality
cd main-repo-quality
```

--------------------------------

### Non-interactive workflow installation

Source: https://github.github.com/gh-aw/guides/reusing-workflows

Use the gh aw add command for non-interactive installation with support for versioning and explicit paths.

```bash
gh aw add githubnext/agentics/ci-doctor              # short form
gh aw add githubnext/agentics/ci-doctor@v1.0.0       # with version
gh aw add githubnext/agentics/workflows/ci-doctor.md # explicit path
```

--------------------------------

### Initialize repository for Claude

Source: https://github.github.com/gh-aw/engines/claude

Run this command to configure the repository for Claude, skipping Copilot-specific files.

```bash

gh aw init --engine claude

```

--------------------------------

### Disable automatic runtime installation

Source: https://github.github.com/gh-aw/reference/agent-runtimes

Configuration to skip automated installation steps when the runner environment is already pre-configured for Docker sbx.

```yaml
---
sandbox:
  agent:
    id: awf
    runtime: docker-sbx
    runtime-install: false
---
```

--------------------------------

### Configure Stdio Server Volume Mounts

Source: https://github.github.com/gh-aw/reference/mcp-gateway

Example configuration for a stdio server with multiple read-only and read-write volume mounts.

```json
{
  "mcpServers": {
    "data-processor": {
      "container": "ghcr.io/example/data-mcp:latest",
      "type": "stdio",
      "mounts": [
        "/var/data/input:/app/input:ro",
        "/var/data/output:/app/output:rw",
        "/etc/config/app.json:/app/config.json:ro"
      ]
    }
  }
}
```

--------------------------------

### Stall Watchdog Warning Example

Source: https://github.github.com/gh-aw/reference/environment-variables

Example of the warning message logged by the harness when the agent CLI produces no output for the configured interval.

```text
[copilot-harness] attempt 1: stall watchdog: no output from '/usr/bin/copilot' for 5m 0s (elapsed=5m 1s pid=1234 warnings=1) - the step may be hung; GitHub Actions will cancel this step in about 14m 59s (timeout-minutes=20)
```

--------------------------------

### Configure Server with Custom Type

Source: https://github.github.com/gh-aw/reference/mcp-gateway

Example of a server configuration utilizing a registered custom type and associated tools.

```json
{
  "mcpServers": {
    "my-custom-server": {
      "type": "safeinputs",
      "tools": {
        "greet": {
          "description": "Greet user",
          "script": "return { message: 'Hello!' };"
        }
      }
    }
  },
  "gateway": {
    "port": 8080,
    "domain": "localhost",
    "apiKey": "secret"
  },
  "customSchemas": {
    "safeinputs": "https://docs.github.com/gh-aw/schemas/mcp-scripts-config.schema.json"
  }
}
```

--------------------------------

### Guardrail failure decision example

Source: https://github.github.com/gh-aw/experimental/experiments

An example showing how a failed guardrail results in a REJECT decision regardless of primary metric performance.

```text
Primary metric: +12%
Tool-failure guardrail: FAIL
Decision: REJECT (guardrail_failed)
```

--------------------------------

### Install gh-aw via GitHub CLI

Source: https://github.github.com/gh-aw/reference/releases

Install the extension using the GitHub CLI extension manager, optionally pinning to a specific version.

```bash
gh extension install github/gh-aw          # latest (default)
gh extension install github/gh-aw@v0.64.5  # pinned version
```
Tokens:
Raw