Module github.trigger

ballerinax/github.trigger Ballerina library

0.9.0

Overview

The GitHub Trigger module allows you to listen to the following events occurring in GitHub:

  • Ping, Fork, Push, Create, Watch
  • Release, Issue, Label, Milestone
  • Pull Request, Pull Request Review, Pull Request Review Comment

This module receives GitHub's webhook events directly - it does not call GitHub's own REST/GraphQL API on your behalf.

Key features

  • Receives 265 GitHub webhook events across 75 service types, from pushes and pull requests to workflow runs
  • Verifies every delivery with the webhook secret (HMAC-SHA256, X-Hub-Signature-256)
  • Typed payload records for each event, with camelCase fields mapped to GitHub's JSON keys
  • Acknowledges each delivery before running your handler, so a slow or failing handler doesn't cause retries
  • Services can be attached on their own path, so several triggers and HTTP services can share one port
  • Trigger services are listed by bal build --export-endpoints (Ballerina 2201.13.6 or later)

Setup guide

Before using this trigger in your Ballerina application, you need a GitHub account with access to the repository/organization you want to receive events from, and a Ballerina service that GitHub can reach over the internet to deliver webhook payloads to. The two sections below cover both a quick local test setup and a production deployment.

Try it out locally

Use this flow to test your webhook handling logic on your own machine before deploying anywhere, using ngrok to expose your local listener to the internet.

  1. Write your service (see Quickstart below) and run it locally with bal run. Note the port it's listening on (8090 by default).

  2. Expose that port with ngrok:

    Copy
    ngrok http 8090

    Copy the Forwarding URL ngrok prints out - this is your temporary public webhook URL.

    ngrok forwarding a public URL to localhost:8090
  3. On the GitHub repository (or organization) you want events from, go to Settings > Webhooks and click Add webhook.

    GitHub repository Webhooks settings page
  4. Fill in the webhook form:

    • Payload URL: the ngrok forwarding URL from step 2.
    • Content type: application/json.
    • Secret: any string - this must exactly match the webhookSecret configured in your service (see Quickstart), since it's used to verify that incoming payloads really came from GitHub.
    GitHub webhook form filled in with Payload URL, content type, and secret
  5. Under Which events would you like to trigger this webhook?, select Let me select individual events and check the events your service handles.

    GitHub webhook individual event selection checkboxes
  6. Click Add webhook. This registers the webhook, but (unlike creating one for the first time in most other flows) does not itself redeliver a test ping - use Recent Deliveries > Redeliver on the webhook's page to trigger one, or just push a real commit. A successful delivery shows a green checkmark back on the Webhooks settings page.

    GitHub webhook showing a successful delivery

Production / business integration

For production use, deploy your Ballerina service somewhere with a stable, internet-reachable HTTPS URL. Ballerina doesn't require any specific hosting platform - containers, a VM, a managed PaaS, or anything else that gives you a stable HTTPS endpoint all work equally well.

Rather than hardcoding webhookSecret as shown in the Quickstart, inject it via Config.toml (or your platform's equivalent configuration/secret mechanism), since it's a configurable value:

Copy
[<your_org>.<your_module_name>.userInput]
webhookSecret = "<your production secret>"

Then follow the same webhook registration steps as above, using your production URL as the Payload URL and this real secret instead of a placeholder.

Compatibility

Version
Ballerina LanguageBallerina Swan Lake 2201.13.0

Why 2201.13.0, not the usual 2201.12.x? This connector's generator tool needs a bal CLI fix that isn't in any 2201.12.x release - see the root README for the full writeup.

Quickstart

To use the GitHub Trigger in your Ballerina application, update the .bal file as follows:

Step 1: Import the GitHub Trigger Ballerina library

Copy
import ballerinax/github.trigger as github;

Step 2: Initialize the GitHub Webhook Listener

Initialize the trigger by providing the listener config and a port number/http:Listener object.

Copy
configurable github:ListenerConfig userInput = {
    webhookSecret: "xxxxxx"
};
listener github:Listener webhookListener = new (userInput, 8090);

webhookSecret should always be set to the same secret configured on the webhook's GitHub page - this is what the trigger uses to verify incoming payloads actually came from GitHub. Without it, the listener rejects every request with 401 Unauthorized.

If you don't provide a port it will use the default port, which is 8090 - webhookSecret should still always be set.

Copy
listener github:Listener webhookListener = new (userInput);

Step 3: Use the correct service type to implement the service

Use the correct service type for the corresponding channel when implementing the service. For example, if you need to listen to Label events, use the LabelService service type as follows. Every remote function declared on a service type must be implemented - Ballerina requires a complete implementation, not just the ones you care about.

Copy
service github:LabelService on webhookListener {

    remote function onLabelCreated(github:LabelPayload payload) returns error? {
        return;
    }

    remote function onLabelEdited(github:LabelPayload payload) returns error? {
        return;
    }

    remote function onLabelDeleted(github:LabelPayload payload) returns error? {
        return;
    }
}

Step 4: Provide remote functions corresponding to the events you're interested in

Remote functions must be implemented inside a service, on the matching service type for the channel you're listening to - for example, github:PushService for push events.

Copy
import ballerina/log;

service github:PushService on webhookListener {
    remote function onPush(github:PushPayload payload) returns error? {
        log:printInfo("Received push event", eventPayload = payload);
    }
}

Step 5: Run the service

Use the bal run command to compile and run the Ballerina program.

Step 6: Register a webhook so GitHub can reach your service

See Setup guide above for the full walkthrough (with screenshots) of exposing your service and registering the webhook, for both local testing and production use.

Examples

The github.trigger module provides practical examples illustrating usage in various scenarios. Explore these examples, covering common webhook event handling use cases.

Report issues

To report bugs, request new features, start new discussions, etc., go to the Ballerina Library repository.

Import

import ballerinax/github.trigger;Copy

Other versions

0.9.0

Metadata

Released date: about 15 hours ago

Version: 0.9.0

License: Apache-2.0


Security

No known vulnerabilities in libraries

Checked on 2026-11-18 via OSV.dev


Compatibility

Platform: java21

Ballerina version: 2201.13.0

GraalVM compatible: Yes


Pull count

Total: 0

Current verison: 0


Weekly downloads


Source repository


Keywords

Name/GitHub Trigger

Area/Developer Tools

Vendor/GitHub

Cost/Freemium

Type/Trigger


Contributors