diff --git a/docs/src/content/docs/reference/concurrency.md b/docs/src/content/docs/reference/concurrency.md index 27455b24062..2e34189376d 100644 --- a/docs/src/content/docs/reference/concurrency.md +++ b/docs/src/content/docs/reference/concurrency.md @@ -82,6 +82,42 @@ This prevents conclusion jobs from colliding when multiple agents run the same w This concurrency group is set automatically during compilation and requires no manual configuration. +## Fan-Out Concurrency (`job-discriminator`) + +When multiple workflow instances are dispatched concurrently with different inputs (fan-out pattern), compiler-generated job-level concurrency groups are static across all runs — causing all but the latest dispatched run to be cancelled as they compete for the same slot. + +Use `concurrency.job-discriminator` to append a unique expression to compiler-generated job-level concurrency groups (`agent` and `output` jobs), making each dispatched run's group distinct: + +```yaml wrap +concurrency: + job-discriminator: ${{ inputs.finding_id }} +``` + +This generates a unique job-level concurrency group per dispatched run, preventing fan-out cancellations while preserving the per-workflow concurrency group at the workflow level. + +Example usage: + +```yaml wrap +concurrency: + job-discriminator: ${{ inputs.finding_id }} +``` + +Common expressions: + +| Scenario | Expression | +|---|---| +| Fan-out by a specific input | `${{ inputs.finding_id }}` | +| Universal uniqueness (e.g. scheduled runs) | `${{ github.run_id }}` | +| Dispatched or scheduled fallback | `${{ inputs.organization \|\| github.run_id }}` | + +:::note +`job-discriminator` is a gh-aw extension and is stripped from the compiled lock file. It does not appear in the generated GitHub Actions YAML. +::: + +:::note +`job-discriminator` has no effect on workflows triggered by `workflow_dispatch`-only, `push`, or `pull_request` events, or when the engine provides an explicit job-level concurrency configuration. +::: + ## Related Documentation - [AI Engines](/gh-aw/reference/engines/) - Engine configuration and capabilities diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md index 4612b470097..f90cb90507b 100644 --- a/docs/src/content/docs/reference/frontmatter-full.md +++ b/docs/src/content/docs/reference/frontmatter-full.md @@ -904,6 +904,15 @@ concurrency: # (optional) cancel-in-progress: true + # Additional discriminator expression appended to compiler-generated job-level + # concurrency groups (agent, output jobs). Use this in fan-out patterns where + # multiple workflow instances are dispatched concurrently with different inputs, + # to prevent job-level concurrency groups from colliding and causing cancellations. + # Supports GitHub Actions expressions. Stripped from the compiled lock file + # (gh-aw extension, not a GitHub Actions field). + # (optional) + job-discriminator: "${{ inputs.finding_id }}" + # Environment variables for the workflow # (optional) # This field supports multiple formats (oneOf):