Observing workflow run status on Github

It is sometimes useful to get notified about the completion of a job executed on your CI service. When talking about manually triggered, long-running workflows, it could be easy to forget about them – when instead of waiting and watching the output log, you just start working on a different task.

GitHub doesn’t share an API that makes it possible to do this easily and efficiently. We are going to use an old-school technique called “short polling.” This fancy name means nothing more than just executing requests in an indefinite loop with a delay in between.

Repository workflow runs list request will be the core of our observer. Take a closer look at the documentation; using query parameters you can filter the results at this early stage. For example: list only workflows triggered by yourself with the actor parameter, specify event which triggered the run or specific branch.

We will just focus on the last run, whatever triggered it, and whoever did it.

JQ is a JSON parser with CLI, we will use it to extract the status of the last run. jqplay is a playground where you can test your queries. Ours will consist of:

.workflow_runs – peek into the array with the list of runs
sort_by( .created_at ) – order items by creation date
.[-1] – select the last one from the list
.status – extract status

Value of the status property can be one of: “queued”, “in_progress”, or “completed”. When it’s “completed,” it makes sense to check if it finished successfully. We need a value of the conclusion property. Can be one of the “success”, “failure”, “neutral”, “cancelled”, “skipped”, “timed_out”, or “action_required”.

Let’s wrap it in a loop, as we want to know when it finishes, not only what’s the current state.

How does it look like in practice?

Some services allow you to easily send push notifications to your mobile devices. You might want to use one to catch your attention. Or if it’s enough, then just play a system sound. Just choose an appropriate one – depending on the conclusion! ;)