{"id":227,"date":"2021-02-02T20:02:28","date_gmt":"2021-02-02T20:02:28","guid":{"rendered":"https:\/\/fde.cat\/?p=227"},"modified":"2021-02-02T20:02:29","modified_gmt":"2021-02-02T20:02:29","slug":"heroku-ci-and-github-checks-integration","status":"publish","type":"post","link":"https:\/\/fde.cat\/index.php\/2021\/02\/02\/heroku-ci-and-github-checks-integration\/","title":{"rendered":"Heroku CI and Github Checks Integration"},"content":{"rendered":"

Heroku CI and GitHub Checks Integration<\/h3>\n

Before we dive into the crux of this article, let\u2019s first get an understanding of what GitHub Checks is and how it will be useful for you when you use any external Continuous Integration (CI) tool like CircleCI<\/a>, Heroku CI<\/a>, or any local tool. The Checks functionality enables integrations to report more than just binary pass or fail to build statuses. Checks integrations can report rich statuses, annotate lines of code with detailed information, and kick off reruns. [Read more in the GitHub Checks Developer Guide<\/a>.]<\/p>\n

In this article, we\u2019ll talk specifically about GitHub Checks integration with Heroku CI, but the same method can be used with any CI tools that expose APIs to fetch CI logs. (Note that some well-known CI tools like CircleCI<\/a>and Jenkins<\/a> have built-in or external plugins for integration, so for them you wouldn\u2019t have to follow this method unless you want to customize the Checks\u00a0output.)<\/p>\n

\"\"<\/figure>\n

Introduction<\/strong><\/h3>\n

This article will help you to set up a Probot <\/a>app as an integration tool between Heroku CI and GitHub Checks using GitHub APIs. The first thing you might wonder is \u201cWhy is this integration needed? Can\u2019t we just use Heroku App to see all the CI\u00a0logs?<\/strong>\u201d<\/p>\n

Well, you can use the Heroku app to see Heroku CI logs\u200a\u2014\u200abut consider a situation where people are contributing to your GitHub repo who don\u2019t have access to your Heroku Pipeline, such as in the case of an open source project with many contributors. In that case, if an automated test, lint, or other CI process fails for their commits, they will only see the boolean result, not the complete reason. With a GitHub Checks integration, they would be able to see the full result on the GitHub Checks tab, which would be very helpful for remediating the\u00a0issue.<\/p>\n

Architecture<\/h3>\n
\"\"<\/figure>\n

How does it\u00a0work?<\/h3>\n

GitHub Webhooks: <\/strong>As per GitHub Docs<\/a>, \u201cWebhooks allow you to build or set up integrations, such as GitHub Apps<\/a>or OAuth Apps<\/a>, which subscribe to certain events on GitHub.com. When one of those events is triggered, an HTTP POST payload is sent to the webhook\u2019s configured URL. Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. You\u2019re only limited by your imagination.\u201d<\/p>\n

Heroku CI<\/strong>: When a test or build gets triggered for a new git commit, it broadcasts the webhook events for Status. The event gets triggered for different stages like in_progress, success, failure, cancel, etc. GitHub catches those events and updates the pull request page build flag. For our scenario, we intercept statusin our integration app.<\/p>\n

DEBUG probot: Webhook received
event: {
   \"event\": \"status\",
   \"id\": \"da6ec6b8-2250-11eb-8843-f0563e0c2987\",
   \"installation\": 12779415,
   \"repository\": \"<Github-owner>\/<Repo-name>\"
}<\/pre>\n
Status (webhook event): When the status of a Git commit changes, the type of activity is specified in the <\/em>actionproperty of the payload\u00a0object.<\/em><\/p><\/blockquote>\n
Probot Integration App: <\/strong>We created a Probot intermediate app that basically intercepts the GitHub webhook events and then executes specific logic as per our requirement. You can catch status events with the following code\u00a0snippet:<\/p>\n
app.on('status', async (context) => {
    console.log('Status event update');
}<\/pre>\n
The \u201ccontext,\u201d in this case, is an object with details related to issues, pull request, repository, actions, etc. You will also find a related CI URL with context.payload.target_url. You can get the state of CI build \/ test using context.payload.state.<\/p>\n
Once you have the CI target URL, you can get logs directly from it or you can create a test log URL from it that will return a simple text log in response. For example, in Heroku CI, you will get a target URL from the context which will be in the format\u00a0of<\/p>\n
https:\/\/dashboard.heroku.com\/pipelines\/<pipeline-id>\/tests\/<test-run-number><\/em><\/p>\n
The URL will look something like this, with your specifics:<\/p>\n
https:\/\/dashboard.heroku.com\/pipelines\/1fa8b9e6-1183-40f6-a66e-701b924b4d90\/tests\/259<\/a><\/pre>\n
And to get a plain text log, you can convert this URL to a different URL format which will be something like https:\/\/api.heroku.com\/pipelines\/<pipeline-id>\/test-runs\/<test-run-id><\/em>. Here\u2019s an\u00a0example:<\/p>\n
https:\/\/api.heroku.com\/pipelines\/1fa8b9e6-1183-40f6-a66e-701b924b4d90\/test-runs\/259<\/a><\/pre>\n
If your Probot app receives a Statusevent with state in_progress, it will create a GitHub Checks run using Checks <\/a>API with the status \u201cIn Progress.\u201d You can do that with the following code:<\/p>\n
https:\/\/medium.com\/media\/9318ca5aa3ddd934e38fa56fd8d3164a\/href<\/a><\/p>\n
Next, if your Probot app receives a Statusevent with the state failure, successor canceled, it will update the GitHub Checks run using the Checks <\/a>API with the status \u201cReceived.\u201d You will fetch all the checks run for a specific commit and then update the checks run (which has the status \u201cIn progress\u201d) with the latest\u00a0status.<\/p>\n
https:\/\/medium.com\/media\/89c51a9ad8c120dc039e92c0aadbdcc4\/href<\/a><\/p>\n
And we are all\u00a0set.<\/strong><\/p>\n
If you want to improve your user experience, there are a couple of additional things that can be tweaked in our integration implementation:<\/p>\n