Workflow:OpenHands OpenHands GitHub Webhook Event Processing
| Knowledge Sources | |
|---|---|
| Domains | DevOps_Automation, AI_Agents, GitHub_Integration |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
End-to-end process for receiving GitHub webhook events, validating user permissions, spawning an AI agent conversation, and posting results back to GitHub.
Description
This workflow handles the complete lifecycle of a GitHub integration event in the OpenHands Cloud Resolver. When a user mentions the OpenHands bot on a GitHub issue or pull request, the system validates the webhook payload, checks the user's repository permissions, runs a solvability analysis, creates a sandboxed agent conversation, and posts the results back as a GitHub comment. The workflow supports issues, issue comments, PR comments, and inline PR review comments.
Usage
Execute this workflow when a GitHub webhook event arrives indicating that a user has requested OpenHands assistance on an issue or pull request. The user must have write access to the repository, and the OpenHands GitHub App must be installed on the target repository.
Execution Steps
Step 1: Webhook Reception and Validation
Receive the incoming GitHub webhook payload and validate its source. The system confirms the message originates from GitHub, then asynchronously processes the payload through the data collector to persist interaction metadata for analytics.
Key considerations:
- Webhook signature verification ensures authenticity
- Payload processing is asynchronous to avoid blocking the response
Step 2: Permission and Eligibility Check
Determine whether the event should trigger an agent job. Filter out system-generated suggestions, check if the user is eligible for proactive conversation starters, and verify the user has write access to the repository by checking collaborator permissions and organization membership.
Key considerations:
- Only users with write access can trigger the bot
- System-generated suggestions (containing the @openhands macro) are filtered out
- Supported event types: labeled issues, issue comments, PR comments, inline PR comments
Step 3: Webhook Payload Parsing
Create a structured view object from the raw webhook payload using the factory pattern. The parser extracts issue or PR metadata, fetches existing comments from the GitHub API, and loads the user's context including custom secrets and repository information.
Key considerations:
- Different view classes handle different event types (issue, PR comment, inline comment)
- Issue context (title, body, comments) is fetched from GitHub API
- Jinja2 templates render the conversation instructions
Step 4: Acknowledgment
Add an "eyes" emoji reaction to the triggering comment or issue to signal that the system has received and is processing the request. Obtain a GitHub App installation access token and store it for subsequent API calls.
Key considerations:
- The eyes reaction provides immediate visual feedback to the user
- Installation tokens are cached via TokenManager for reuse
Step 5: Solvability Analysis
Run an LLM-based solvability analysis on the issue to estimate difficulty and feasibility before committing compute resources to a full agent session. The analysis generates a brief report that is included in the acknowledgment message.
Key considerations:
- LLM spend is accumulated before starting the runtime container
- Solvability analysis is optional based on user settings
Step 6: Conversation Creation
Initialize a new conversation by creating metadata records, rendering instruction templates, and setting up the agent session. Register a callback processor (V1 path) to handle post-execution events. The conversation runs inside a remote sandboxed container.
Key considerations:
- Conversation metadata links the agent session to the GitHub event
- The V1 callback processor listens for ConversationStateUpdateEvent with execution_status finished
- Provider tokens and custom secrets are injected into the sandbox
Step 7: Progress Notification
Post an acknowledgment comment to the GitHub issue or PR with a link to the live conversation. The message includes the solvability report if available and a direct link for the user to track agent progress.
Key considerations:
- Message format: "I'm on it! {user} can track progress at {link}"
- Inline PR comments use review comment reply API, others use issue comment API
Step 8: Agent Execution and Summary Callback
The agent works autonomously inside the sandboxed runtime. When execution finishes, the V1 callback processor queries the agent server for a summary of actions taken and posts the summary back to the originating GitHub issue or PR comment.
Key considerations:
- Summary is requested via POST to /api/conversations/{id}/ask_agent
- Authentication uses the session API key
- Error messages are posted back to GitHub if the agent fails