Skip to content

Update gh-aw docs for setup prerequisites and triggers #1284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 2 commits into
base: main
Choose a base branch
from
+4 −3
Open

Update gh-aw docs for setup prerequisites and triggers #1284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9398955
Update gh-aw docs for setup and triggers
github-actions[bot] Jun 15, 2026
a6621e7
Merge origin/main and resolve conflicts in gh-agent-workflows.md
Copilot Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/developing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ Internal-only workflows (e.g., `upgrade-check.md`, `workflow-patrol.md`, `ci.yml

## Prerequisites

- [Go](https://go.dev/dl/) — required by `make setup` to build the `gh-aw` compiler
- [Go](https://go.dev/dl/) — optional; only needed for non-release gh-aw compiler builds

@github-actions github-actions Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Make the verification step consistent with the new optional prerequisite. On a clean release-based setup, make setup can install the official .bin/gh-aw without Go (see Makefile:143-146), but the next documented command still unconditionally runs go version at line 22 and fails when Go is absent. Please verify curl/wget (and optionally gh) here, or make the Go check conditional for source builds.

- [GitHub CLI (`gh`)](https://cli.github.com/) — installed automatically by `make setup` on Linux, but must be pre-installed on macOS
- `curl` or `wget` — used to download the official gh-aw release compiler binary

Verify with:

Expand Down
4 changes: 2 additions & 2 deletions docs/workflows/gh-agent-workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ setup-commands: |

Each workflow has two layers:

1. **Workflow** (`gh-aw-*.md` -> `gh-aw-*.lock.yml`): The agent logic, compiled by `gh-aw`. Triggers only on `workflow_call` with standard inputs (`additional-instructions`, `setup-commands`).
2. **Trigger** (`<name>/example.yml`): A plain YAML file that defines the actual event triggers (schedule, PR events, slash commands, etc.) and calls the compiled `.lock.yml` via `uses:`. These serve as both examples for consumers and dogfood for this repo (copied to `.github/workflows/trigger-*.yml` by `scripts/dogfood.sh` for workflows not listed in `EXCLUDED_WORKFLOWS`).
1. **Workflow** (`gh-aw-*.md` -> `gh-aw-*.lock.yml`): The agent logic, compiled by `gh-aw`. Workflows expose `workflow_call` with standard inputs (`additional-instructions`, `setup-commands`) and a `COPILOT_GITHUB_TOKEN` secret. Some source templates also declare direct comment/review/discussion triggers (`issue_comment`, `pull_request_review_comment`, `discussion_comment`) so the compiled workflow can be activated by reactions with the required permissions.

@github-actions github-actions Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Please do not document direct event triggers or a COPILOT_GITHUB_TOKEN secret on source templates unless those files actually declare them. For example, .github/workflows/gh-aw-mention-in-pr.md:30-32 has only workflow_call, while gh-agent-workflows/mention-in-pr/example.yml:2-6 owns the issue_comment and pull_request_review_comment triggers; gh-agent-workflows/DEVELOPING.md:36 also states templates trigger only via workflow_call. As written, maintainers may edit the wrong layer and expect direct activation that never occurs.

2. **Trigger** (`<name>/example.yml`): A plain YAML file that defines the installable event wiring for each workflow (schedule, PR events, slash commands, etc.) and calls the compiled `.lock.yml` via `uses:`. These serve as both examples for consumers and dogfood for this repo (copied to `.github/workflows/trigger-*.yml` by `scripts/dogfood.sh` for workflows not listed in `EXCLUDED_WORKFLOWS`).

Consumer repos copy a workflow's `example.yml`, change the `uses:` path if needed, and customize the `with:` inputs. Updates propagate automatically when this repo updates the `v0` tag on release.
Loading