Wake an agent from GitHub webhooks

A GitHub trigger wakes an agent when something happens in a repository: a pull request opens, an issue gets a comment, a release ships. Typical uses are a first review of every new pull request, a triage note on new issues, or release notes drafted the moment a release is published.

There are two ways to set it up. If Integrations is on your account, connect GitHub once with a fine-grained token and pick events from a list: Qoren adds the webhook to the repository for you. Otherwise, or for an event the connected list does not offer, create a trigger with its own URL and secret and add them to the repository yourself. For how triggers work in general (rules, Act or Propose only, the delivery log), see let an event wake your agent.

Before you start#

• An agent that has finished setting up.
• Admin access to the GitHub repository (or organization) you want to connect. GitHub only lets admins add webhooks.

The easy way: connect GitHub#

1. Connect GitHub with a fine-grained token, name the repository or organization its triggers watch, and give the agent access, as in connect GitHub to Qoren.
2. Open the agent, click Triggers, and under From your connected tools click Add a connected trigger.
3. Pick an event, such as Pull request opened, Issue opened, Pull request merged or Workflow run failed, write the rules, and click Add trigger.

Qoren adds the webhook to the repository (or organization) with its own secret, and the connected events already say what happened, so Pull request merged never wakes the agent for a closed one. GitHub never retries a delivery that failed, so Qoren's daily check asks GitHub to send again the ones that failed in the last 3 days. There is nothing to paste. See wake an agent from a connected tool.

Already have a GitHub trigger with a URL? Once GitHub is connected and the agent has access, open it and click Switch to connected.

Or use a URL and a secret#

For other GitHub events, such as Dependabot alerts or deployment statuses, or when Integrations is not on your account yet, create a trigger with its own URL and secret.

Create the trigger in Qoren#

1. Open the agent, click Triggers in the tabs under its name, then click Add a trigger.
2. Name it in What is this for?, for example "New pull requests".
3. Under Where does it come from?, pick GitHub (1).
4. Under Which events?, pick what the agent should act on, for example pull_request (2).

12

5. Write the rules: what the agent should do with each event.
6. Leave Already have a signing secret? empty so Qoren makes one, then click Create trigger.
7. Copy the Webhook URL and the Signing secret from the section that appears. They are shown only once.

The events offered for GitHub are push, pull_request, pull_request_review, pull_request_review_comment, issues, issue_comment, dependabot_alert, release, workflow_run, check_run, deployment_status and star. You can type any other GitHub event name and press Enter.

Add the webhook in GitHub#

GitHub's own guide is creating webhooks, and every event is described in webhook events and payloads.

1. In GitHub, open the repository, then Settings, then Webhooks, and click Add webhook. For every repository in an organization, do the same in the organization's settings.
2. Paste the Webhook URL into Payload URL.
3. Set Content type to application/json, so the agent gets the event as readable JSON.
4. Paste the Signing secret into Secret.
5. Under Which events would you like to trigger this webhook?, choose Let me select individual events and tick the same events you picked in Qoren.
6. Keep Active ticked and click Add webhook.

Check that it works#

GitHub sends a ping event as soon as you add the webhook.

• If your trigger listens for specific events, the ping shows up in the trigger's Deliveries as Ignored. That is good news: a delivery only gets that far after its signature checks out, so the URL and the secret are right.
• If nothing appears in Deliveries, open the webhook in GitHub and look at Recent Deliveries. A refused signature means the secret in GitHub does not match; replace the pair in Qoren with New URL and secret and paste both again.

To try the agent's side without waiting for real activity, click Send a test event in the trigger. It sends a made-up sample and runs the agent on it.

What the agent receives#

GitHub names the event in a header, so the trigger matches on names like pull_request or issues. What happened inside that event, such as a pull request being opened, closed or merged, is in the body as action. Say in your rules which actions matter, for example: "Only act when the action is opened. Ignore closed and synchronize."

The agent gets your rules and the full event body GitHub sent, labelled as data from outside, and it replies with a short summary that appears in the delivery log. If GitHub retries or redelivers an event, Qoren recognises the signed body it already handled and does not run the agent twice.