Problem
Currently, the strategy / matrix support in gh-aw only applies to custom jobs defined under jobs: in the frontmatter (e.g., the BatchOps pattern). The agent job itself — the core AI execution job — does not support matrix strategy, meaning it always runs as a single instance per workflow run.
This is a limitation for use cases like randomized testing at scale, where you want to dispatch N parallel agent threads with different parameters (random seeds, test configs, shards) and have each agent instance work independently and concurrently.
Use Case
I want to run randomized test campaigns where:
- Multiple agent instances run in parallel as matrix jobs (e.g., 5–10 concurrent threads)
- Each instance receives different matrix parameters (e.g.,
seed, test-suite, scenario)
- Each agent independently generates and executes randomized test scenarios using its own AI session
- Results from all parallel agents are aggregated at the end
Today, achieving this requires either:
- Running agents sequentially (slow, defeats the purpose)
- Using
workflow_dispatch fan-out with multiple workflow runs (wasteful, hard to coordinate, hits per-engine concurrency)
- Custom jobs with matrix that call back into agent workflows (fragile, not a first-class pattern)
Proposed Solution
Allow strategy on the agent job, either at the top level or under engine:
---
on:
workflow_dispatch:
inputs:
threads:
default: "5"
strategy:
matrix:
thread: [0, 1, 2, 3, 4]
fail-fast: false
max-parallel: 5
engine:
id: copilot
concurrency:
group: "gh-aw-copilot-${{ github.workflow }}-${{ matrix.thread }}"
tools:
bash: ["pytest", "jq"]
---
# Randomized Test Runner — Thread ${{ matrix.thread }}
Run randomized test suite using seed derived from thread index ${{ matrix.thread }}.
Each thread independently selects and executes a random subset of tests.
Key requirements:
- Matrix parameters available in markdown body via
${{ matrix.* }} expressions
- Per-instance concurrency groups so parallel agent instances don't cancel each other
fail-fast: false support so one failing agent doesn't kill the others
max-parallel to cap concurrent AI sessions and manage token/API costs
Prior Art
Alternatives Considered
| Approach |
Limitation |
workflow_dispatch fan-out (dispatch N separate runs) |
No shared context, hard to aggregate, per-engine concurrency blocks |
job-discriminator with dispatch-ops |
No matrix parameters in the agent prompt |
Custom job with matrix + assign-to-agent safe output |
Fragile, adds a full extra job layer, not first-class |
Problem
Currently, the
strategy/matrixsupport in gh-aw only applies to custom jobs defined underjobs:in the frontmatter (e.g., the BatchOps pattern). The agent job itself — the core AI execution job — does not support matrix strategy, meaning it always runs as a single instance per workflow run.This is a limitation for use cases like randomized testing at scale, where you want to dispatch N parallel agent threads with different parameters (random seeds, test configs, shards) and have each agent instance work independently and concurrently.
Use Case
I want to run randomized test campaigns where:
seed,test-suite,scenario)Today, achieving this requires either:
workflow_dispatchfan-out with multiple workflow runs (wasteful, hard to coordinate, hits per-engine concurrency)Proposed Solution
Allow
strategyon the agent job, either at the top level or underengine:Key requirements:
${{ matrix.* }}expressionsfail-fast: falsesupport so one failing agent doesn't kill the othersmax-parallelto cap concurrent AI sessions and manage token/API costsPrior Art
strategyschema from custom jobs (was an empty-object-only definition). The BatchOps pattern now shows working matrix on custom jobs, but not on the agent job.concurrency.job-discriminatorfeature already solves part of this (fan-out without cancellation), but doesn't provide matrix parameters or parallel agent instances within a single workflow run.Alternatives Considered
workflow_dispatchfan-out (dispatch N separate runs)job-discriminatorwith dispatch-opsassign-to-agentsafe output