ballerinax/trigger.github Ballerina library

Overview

The GitHub Trigger module allows you to listen to following events occur in GitHub.

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

This module supports GitHub API v4 version and only allows to perform functions behalf of the currently logged in user.

Prerequisites

Before using this trigger in your Ballerina application, complete the following:

• Create github account

Quickstart

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

Step 1: Import the GitHub Webhook Ballerina library

First, import the ballerinax/github.webhook and ballerina/websub modules into the Ballerina project as follows.

import ballerinax/trigger.github;

Step 2: Initialize the GitHub Webhook Listener

Initialize the Trigger by providing the listener config & port number/httpListener object.

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

Listener config is not mandatory If you haven't setup secret in webhook page we can omit it and initialize as follows.

listener github:Listener webhookListener = new (listenOn = 8090);

If you don't provide a port it will use the default port which is 8090.

listener github:Listener webhookListener = new ();

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

Use the correct service type for the corresponding channel when implementing the service. Ex :- If you need to listen to Issue events you may use IssuesService service type as follows.

service github:IssuesService on githubListener {
    
    remote function onAssigned(github:IssuesEvent payload) returns error? {
        return;
    }

    remote function onClosed(github:IssuesEvent payload) returns error? {
        return;
    } 

    remote function onLabeled(github:IssuesEvent payload) returns error? {
        return;
    }

    remote function onOpened(github:IssuesEvent payload) returns error? {
        return;
    }

    remote function onReopened(github:IssuesEvent payload) returns error? {
        return;
    }

    remote function onUnassigned(github:IssuesEvent payload) returns error? {
        return;
    }

    remote function onUnlabeled(github:IssuesEvent payload) returns error? {
        return;
    }
}

Step 4: Provide remote functions corresponding to the events which you are interested on

The remote functions can be provided as follows.

remote function onPush(github:PushEvent payload) returns error? {
    log:printInfo("Received push-event-message ", eventPayload = payload);
}

Step 5: Run the service

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

Step 5: Configure Github webhook with the URL of the service

• Create a webhook in github following github documentation
• Provide the public URL of the started service as the Payload URL (Add a trailing / to the URL if its not present).
• Provide application/json for the content type.
• Support for secret field will be available in the next github trigger releases.
• Select the list of events you need to subscribe to and click on Add webhook.

This will add a subscription to github event api and the ballerina service functions will be triggerred once an event is fired.