github as their event source.
For events from services other than GitHub, such as Linear, Stripe, or Slack, see
Event-Based Automations.
Prerequisites
GitHub event automations require some one-time setup before events will flow. If any step is missing, automations will appear to work (manual triggers succeed) but GitHub events will silently never arrive.1. Install the GitHub App
The GitHub App you configured for OpenHands Enterprise must be installed on the GitHub organization that owns the repositories you want to monitor. Create and install the app by following the GitHub integration guide. The app needs access to the repositories that will generate events.2. Create an OpenHands Team Organization
If you’re working with repositories owned by a GitHub organization (e.g.,myorg/my-repo), you need an OpenHands team organization — not just a personal account. GitHub events for org repos are routed to team orgs, not personal orgs.
If you don’t already have one, create a team organization — see What Are Organizations for details and how to get started.
3. Claim Your GitHub Organization
Your OpenHands team org must claim the GitHub organization to establish the link between GitHub webhooks and your OpenHands org. Claiming tells the event router: “Events for repos in this GitHub org should go to this OpenHands team org.” To claim a GitHub org:- Switch to your team org using the org switcher in the sidebar
- Go to Organization Settings
- In the Git Conversation Routing section, find your GitHub org
- Click Claim
4. Create the Automation Under the Team Org
Make sure you are switched to the team org (not your personal org) when creating the automation. The automation must live in the same org that claimed the GitHub organization — otherwise events won’t match.5. (Optional) Add Service Accounts to the Team Org
If you’re using a service account (like a bot account) to create or own automations, that account must be a member of the team org. Invite them from the Organization Members page.Troubleshooting
If your automation doesn’t trigger on GitHub events:GitHub App not installed on the org
GitHub App not installed on the org
The GitHub App you configured for OpenHands Enterprise must be installed on the GitHub organization that owns your repositories. Follow the GitHub integration guide and verify the app is installed with access to the relevant repos. Without this, no webhook events are sent to OpenHands.
GitHub org not claimed
GitHub org not claimed
The most common cause. Go to Organization Settings → Git Conversation Routing and check if your GitHub org shows as claimed. If not, click Claim. See Claiming Git Organizations.
Automation in personal org instead of team org
Automation in personal org instead of team org
GitHub events for org repos are routed to the team org that claimed the GitHub org. If you created the automation under your personal org, events will never reach it. Switch to the team org and recreate the automation.
Event type or filter mismatch
Event type or filter mismatch
Double-check that the event type (e.g.,
pull_request.labeled) and filter expression match the action you’re testing. Use wildcards like pull_request.* to match all actions during debugging.Automation is disabled
Automation is disabled
Verify the automation is enabled. You can check via the automations list or by asking OpenHands to list your automations.
workflow_run events never arrive
workflow_run events never arrive
The GitHub App must subscribe to the Workflow runs event. Apps created before this event was added to the setup helper subscribe only to issue comments, pull requests, and pull request review comments. In the app’s settings on GitHub, open Permissions & events, enable Workflow runs under Subscribe to events, and save. The app’s existing Actions permission already covers this event.
status, check_suite, or check_run events never arrive
status, check_suite, or check_run events never arrive
The GitHub App must subscribe to these events, and apps created before the setup helper added them do not. In the app’s settings on GitHub, open Permissions & events, make the changes below, and save:
- For
status, enable Status under Subscribe to events. The app’s existing Commit statuses permission already covers this event. - For
check_suiteandcheck_run, set the Checks repository permission to Read-only, then enable Check suite or Check run under Subscribe to events. Each organization that installed the app must accept the new permission before GitHub sends these events.
Create GitHub Event Automations
Create automations that respond to GitHub events without any webhook setup.Example: Auto-Review PRs with a Specific Label
When a PR is labeled withopenhands, automatically review it:
- Trigger type:
event - Source:
github - Event:
pull_request.labeled - Filter: Matches PRs labeled
openhands
Example: Respond to @openhands Mentions
Example: Gate on CI Results
Send work back to an agent when CI fails, or move it forward when CI passes:- Trigger type:
event - Source:
github - Event:
check_suite.completed - Filter:
check_suite.conclusion == 'failure' && check_suite.app.slug == 'github-actions'
Every event names the commit:
workflow_run.head_sha, check_suite.head_sha, check_run.head_sha, or sha. Workflow run and check events also list the commit’s pull requests in a pull_requests array, which is empty for a pull request from a fork.
GitHub reports each CI result separately and sends no event for a commit as a whole. A commit with three workflows produces three
workflow_run.completed events and three check_suite.completed events, and a status event fires on every change, including pending. To act on a failure, trigger on any failed result. To act on success, filter on the one workflow, check, or status context that must pass, such as workflow_run.name == 'CI' or context == 'ci/build'.Available GitHub Events
Use wildcards like
pull_request.* to match all actions for an event type.
Filtering Events
Filters let you narrow which events trigger your automation. They use JMESPath expressions to match fields in the event payload—so you can trigger only on specific labels, users, branches, or other conditions.OpenHands extends standard JMESPath with custom functions including
icontains (case-insensitive string match) and glob (wildcard path matching). It also supports ! (negation), && (AND), and || (OR) as boolean operators. These extensions are not part of the JMESPath specification.contains(...)— match a specific labelicontains(...)— case-insensitive mention in a comment bodyglob(...)— match repos in your org with wildcards==— exact match (e.g., push to main branch only, or only failed workflow runs withworkflow_run.conclusion == 'failure')&&— combine multiple conditions
Next Steps
- Event-Based Automations - Trigger automations from custom webhooks
- Automations in OpenHands Enterprise - Sharing, run identity, and permissions
- GitHub Integration - Create and configure the GitHub App
- Managing Automations - Update, disable, or delete automations

