Github Pages Publish Notification

22 Feb 2020

Last year I finally made my big web site move from Squarespace to Github Pages. In that post I went into some of the background of the move, and while the vast majority of things have improved in terms of my requirements, one thing has been much worse. For the site I use a static web site generator known as Jekyll. It works by converting various configuration templates and content files into a web site. Locally, on my Macbook Pro, I tend to use an incremental generation during my testing and within a few seconds it churns out the new site. With a full site generation it actually takes closer to a minute. This site is many hundreds of cross referenced pages, so it takes a while.

When I upload the content to Github Pages, which also utilises Jekyll, it takes even longer. Minutes in fact. This is where it falls down in comparison to Squarespace. I don’t get a near instant publish. This means that I could inadvertently post links too soon, or I have to check back to see if it has published yet. Sometimes, there can even be failures (very few and far between fortunately). This has been an annoyance for a few months now, and so I recently took a look at creating something to help me with this.

The Design

Given that I can’t influence how quickly Github generates my site without changing the site size or moving host, I realised immediately that what I was going to need was some sort of monitor that could tell me when publishing was complete and if there were any errors. The first thing to do was to look at the Github events documentation to see if I could find anything that could trigger when the site completed publishing. I was fortunate in this, and found that Github does indeed have an event that matched my requirements. It’s called Page Builds.

Github can trigger webhooks, sending data and calls to a URL to trigger an action remotely, when these events occur. Examining the details for the Page Builds event, I could see that I could access data about the success of the publish, which meant that I could use the web hook to send that data somewhere else when the event occurred.

The data itself is in a raw format at this point, so I knew I was going to want to do at least some simple parsing and formatting to get it into a format I could use for a notification. For this I decided to make use of an online integration service called Integromat. It offers a variety of data manipulation features that are well beyond something like IFTTT, and I have a somewhat underutilised free tier account, so it seemed to be a good fit.

The solution would now trigger on the page publish at Github and pass the information to Integromat where I could process it. But how to get the notification? My current phone is an iPhone, and I also have an Apple watch and while I referenced above that I’m typically publishing from my Macbook Pro, the truth is I occasionally publish from my iPhone, my iPad, and even through direct updates on Github via the editing in the web interface. It therefore made sense to want to receive the notifications to my iPhone (and watch).

I had a few options that I could use for receiving a notification from Integromat, but the one I selected is an app/service called Pushcut. I chose this because it gave me an option to easily add actions to notifications. What actions would I want to subsequently trigger? Well I had a few ideas which you can read about below.

The Implementation

I began the implementation by creating a new notification in Pushcut as the final destination. I’ll come back to it towards the end as it will probably make more sense that way given it is more or less the end point. But simply note that I named this notification “ThoughAsylum Published”.

The next step was to create a scenario in Integromat. Scenarios are the sets of inputs transformations and outputs to occur. I began with the input - creating a webhook. This then established a URL to use to trigger the scenario. As per the webhook guidelines I copied the URL, and set it waiting for an input so that the incoming data structure could be determined.

Armed with the webhook URL I then accessed my web site repository in Github. From there I navigated to the webhooks section of the settings tab. Selecting Add webhook creates a new outgoing webhook trigger action. I entered the Integromat web hook URL as the Payload URL, set the Content Type as application/x-www-from-urlencoded, and set it to trigger for just a single event, Page builds. Once activated, I then uploaded a file to the repository to trigger a page build.

When the publish completed, the Integromat webhook was triggered, and the webhook module captured and auto-determined the data structure.

The details for the webhook then look like this.

The data payloads that are received look like this.

I then linked in the transformation module and the output module. JSON and Pushcut respectively. The Integromat scenario then looks like this.

The JSON module isn’t doing any radical transformation. It is just in place to allow direct reference to individual elements in the payload.

This then allowed me to pick out three useful details to send to Pushcut as part of the body of the notification.

Here you’ll notice that this is where I also set which Pushcut notification to trigger - “ThoughtAsylum published”. Let’s take a look at what that actually does.

When Integromat finished processing, Pushcut is immediately triggered on my i*OS devices.

But this isn’t quite where things end. This is because I’ve added some further Shortcuts based actions to the notification. The notification is defined as follows in Pushcut.

There are two actions, and you can expand the sections below for screenshots:

1. Update in Working Copy - Working Copy is the Github client app I use on my iOS devices. It has Shortcuts integration, and so I created a shortcut to fetch updates from Github and get the on-device repository up to date. Once done, the shortcut issues a notification of completion, and exits to the device home screen.

2. Announce Last Post - this shortcut retrieves the title and URL for the latest post from the site RSS feed, and places them on the clipboard. It then extracts the home/blog page post thumbnail from the page meta-data, and saves a copy to the device photo library. The shortcut finally offers to open one of several social apps to allow me to create a post about the new site post with all the data I want at hand. I like to choose when and what precise details to post, so I prefer this approach over a fully automated one which I could implement using the Integromat scenario.

This solution has been working well for me over the last few weeks. It gives me the information I was looking for, and it allows me to act on it if I should so choose. If you have a similar challenge using Github pages, I’d say it’s well worth the 10-15 minutes effort of setting this up. If you are a Shortcuts user and a Pushcut subscriber, then that simply opens up even more scope for what you can do with the information about your site publishing.