12 min read
React to GitHub events
Start an agent the moment a pull request opens, a build goes red, or a tag lands — filtered down to exactly the events you want it on.
- 01
Connect GitHub and choose the repositories
Authorize GitHub from Settings → Integrations and select which repositories the connection covers. That selection is the ceiling on everything an agent can reach, so start with one repository while you build confidence.
- 02
Pick the event that matches the task
A reviewer runs on `pull_request.opened` and `pull_request.synchronize`. A build explainer runs on `workflow_run.completed`. A release notes writer runs on `tag.created`. An issue triager runs on `issues.opened`. Choose the event where the work actually begins.
- 03
Filter the trigger down
Field filters keep the agent off the pull requests you did not mean. Filter by base branch so it ignores work on long-lived feature branches, or by label so a PR opts in one at a time — `agent-review` on the pull requests you want, and nothing else fires.
- 04
Write the prompt against the event payload
The agent receives the event that started it, so the prompt can refer to the pull request, the workflow run, or the tag directly. Tell it what to read first: the diff, the contributing guide, the last twenty merged reviews.
- 05
Start with a label filter and a comment
Have the agent post a comment rather than an approving review, and gate it behind a label. Add the label to a handful of your own pull requests, read what it wrote, then widen the filter once the reviews are worth reading.
- 06
Decide who can change it
A workflow that comments on pull requests is a workflow your team will read closely. Org roles decide who may edit it — admins and editors change the prompt, users run it — and resource visibility keeps it scoped to the team that owns it.
Keep going
Next in the track
10 min
Run your first agent
Describe a task in plain English, give the agent a tool to reach for, and watch it work. Ten minutes from an empty workspace to a run you can read end to end.
8 min
Put an agent on a schedule
Turn a working prompt into a standing task. Describe the cadence the way you would say it out loud, and Helios writes the cron expression for you.
9 min
Share with your team
Hand an agent to the people who need it. Roles decide who may edit, visibility decides who may see, and every run leaves a record of what happened.
Templates
Put it to work
Templates that use what this guide covers.
Engineering
Pull request reviewer
Reviews every pull request against your conventions, leaves inline comments, and posts a weekly digest of review load and CI health.
Engineering
Release notes writer
Turns a new tag into release notes grouped by theme, publishes them on GitHub, and files a changelog entry in Notion.
Engineering
Incident postmortem drafter
Reconstructs the incident timeline from Slack and GitHub, names the triggering change, and drafts the write-up in Notion.
Try it in your workspace.
Start free, connect a tool, and describe the first task in plain English.