Document branches/paths mutual exclusivity in workflow schema

[Copilot]

Adds $comment fields to main_workflow_schema.json documenting GitHub Actions' mutual exclusivity constraints: branches/branches-ignore and paths/paths-ignore cannot be used together.

Changes

• 14 $comment fields added across push, pull_request, pull_request_target, and workflow_run event filters
• Each comment follows pattern: "Mutually exclusive with [field]. GitHub Actions requires only one to be specified."
• Documentation-only change—no validation logic added

Context

JSON Schema lacks native mutual exclusivity support. These comments provide developer-facing documentation while runtime validation is deferred to #5804.

Example

"branches": {
  "type": "array",
  "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.",
  "description": "Branches to filter on",
  "items": { "type": "string" }
}

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/user
  • Triggering command: /usr/bin/gh gh api user --jq .login tags/v5 988557/b276/vet.cfg /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -uns�� out.git out.git /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet GOSUMDB %H %ct %D g/workflow/node_xterm-color /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login ference.git ference.git ache/go/1.25.0/x64/pkg/tool/linux_amd64/compile GOSUMDB GOWORK ules/.bin/sh ache/go/1.25.0/x--json -uns�� 988557/b355/_pkg_.a /tmp/go-build109988557/b072/vet.cfg 988557/b355=> n' '!../../workfinfocmp zation_test.go x_amd64/compile /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login up-uv.git -buildtags 3615a56d8f846bd00ca79a541fec35e93ca/log.json -errorsas -ifaceassert -nilfunc /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -ato�� -bool -buildtags (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Document branches/paths mutual exclusivity in schema</issue_title>
<issue_description>## Objective

Add $comment documentation to schema for GitHub Actions mutual exclusivity rules: branches/branches-ignore and paths/paths-ignore cannot be used together.

Context

GitHub Actions requires that branches and branches-ignore (and similarly paths and paths-ignore) be mutually exclusive. The schema doesn't validate this constraint because JSON Schema lacks native mutual exclusivity support. Adding documentation via $comment helps developers and future maintainers understand the constraint.

Approach

Add $comment fields to the schema for both push and pull_request event filters to document the mutual exclusivity requirement.

Files to Modify

• Update: pkg/parser/schemas/main_workflow_schema.json
  • push event filters (branches, branches-ignore, paths, paths-ignore)
  • pull_request event filters (branches, branches-ignore, paths, paths-ignore)

Implementation

Add $comment to each filter field:

"branches": {
  "type": "array",
  "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.",
  "description": "Branches to filter on",
  "items": { "type": "string" }
},
"branches-ignore": {
  "type": "array",
  "$comment": "Mutually exclusive with branches. GitHub Actions requires only one to be specified.",
  "description": "Branches to ignore",
  "items": { "type": "string" }
},
"paths": {
  "type": "array",
  "$comment": "Mutually exclusive with paths-ignore. GitHub Actions requires only one to be specified.",
  "description": "Paths to filter on",
  "items": { "type": "string" }
},
"paths-ignore": {
  "type": "array",
  "$comment": "Mutually exclusive with paths. GitHub Actions requires only one to be specified.",
  "description": "Paths to ignore",
  "items": { "type": "string" }
}

Locations to Update

1. push.branches / push.branches-ignore
2. push.paths / push.paths-ignore
3. pull_request.branches / pull_request.branches-ignore
4. pull_request.paths / pull_request.paths-ignore

Acceptance Criteria

• $comment added to all 8 filter fields (4 pairs × 2 events)
• Comments accurately describe the mutual exclusivity constraint
• Schema is valid JSON (run make build to verify)
• No change to existing validation behavior (this is documentation only)

Testing

# Rebuild binary with updated schema
make build

# Verify schema is still valid and embeds correctly
./gh-aw --version

# Existing behavior should be unchanged (invalid configs still compile)
echo '---
on:
  push:
    branches: [main]
    branches-ignore: [dev]
---
Test' > /tmp/test-both.md

./gh-aw compile /tmp/test-both.md  # Should still succeed (no runtime validation yet)

Notes

This is a documentation-only change. Runtime validation will be added in a separate issue (#5804 tracks the parent). The $comment field is part of JSON Schema spec and is ignored by validators but visible to developers reading the schema.
Related to #5804

AI generated by Plan Command for discussion #5799

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Document branches/paths mutual exclusivity in schema #5807

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.