Integrating Flock With GitHub

Often developers use integration of mailing lists to get notifications from their GIT repositories. One of the ways to do it is using webhooks provided by GitHub:

Webhooks allow external services to be notified when certain events happen within your repository. When the specified events happen, GitHub will send a POST request to each of the URLs you provide. Learn more about them Webhooks Guide.

Getting GitHub pull requests’ notifications in Flock

In a nutshell, we have to enable us to receive notifications about the pull requests from GitHub and then we have to route those notifications to the Flock application.

With Flock, you can integrate it with any group in the application. All you need to do is specify which repositories to monitor for the pull requests event, and use an incoming webhook feature of Flock to send the notification message to Flock’s group.

So basically, we will be playing with two webhooks here:

• Flock webhook: Flock provides a feature to create an incoming webhook. Incoming webhook allows you to post messages to a Flock group from another service. We will be creating one for our use.
• GitHub webhook: We will be adding a webhook on GitHub also so that whenever any event, related to a pull request, happens on GitHub, we get notified.

Configuring a Flock incoming webhook

Configuring an incoming webhook on Flock is fairly simple

1. Login to http://admin.flock.co
2. Use “Add” option next to Incoming Webhooks.

Screenshot image for steps 1 and 2.

3. Select the Flock group on which you want to send your notification messages.

4. You can configure few more options like “name” of your webhook or an icon. Adding an icon is optional, so for now, we can skip adding icon.

5. Click save.

Screenshot image for steps 3, 4 and 5.

6. On clicking save, your webhook will be created and you will get the URL for your webhook like this:

Screenshot image for step 6.

Now we are done with the process of creating the incoming webhook on Flock’s platform.

Whenever you want to send a message to the group via this newly created webhook, we just have to make a POST request with text message. For example:

curl -X POST -H 'Content-type: application/json' -d '{ "text":  "some text"}' https://api.flock.co/hooks/sendMessage/<token>

Creating a service to route GitHub’s notifications to Flock

Whenever, GitHub notifies your service, it sends you a payload. In case of pull request event, payload consists of following:

• action: The action that was performed.
• number: The pull request number.
• pull_request: The pull request itself.

Action can be one of “assigned”, “unassigned”, “labeled”, “unlabeled”, “opened”, “closed”, or “reopened”, or “synchronize”. If the action is “closed” and the merged key is false, the pull request was closed with unmerged commits. If the action is “closed” and the merged key is true, the pull request was merged.

For our service, we want to get notified only when pull request is opened, reopened, closed and merged. By parsing the payload I got from GitHub notification, I am creating the following message text:

$msg = “<user> <action> a pull request: ‘<title>’, <url>”;

• user: Actor of the event.
• action: Action performed on the pull request. Opened, merged etc.
• title: Title of the pull request.
• url: url of the pull request.

After creating the required notification message text, I am sending it to the Flock’s webhook I created in previous section.

You can check the complete code of my service at: https://github.com/uditiiita/Flock-Github-Hook

Creating a GitHub webhook:

Now only the last part is left where we have to tell GitHub that this is my service URL and hit it whenever you want to notify me.

1. Go to the webhooks settings of your repository (replace github_user_name and respository_name with yours): https://github.com/<github_user_name>/<respository_name>/settings/hooks
2. Click on “Add Webhook”:

3. Fill in URL of your service you created in the previous section. Secret is optional, so you can skip it:

4. Choose “Let me select individual events” and then tick only “Push” from the list of events.

5. Click “Add webhook”.

Thats it. your webhook is created.

Now whenever there is any event on any of the pull requests of the repository, GitHub will send the event payload to your service.

Your service will then check that is that an event in which I am interested? Yes? Your service will then create the message text and send it to Flock.