How to Integrate GitHub Checks API to Manage CI Results in Node.js

Integrate GitHub Checks API in Node.js

• Firstly, you need to have a GitHub App set up, which will allow authentication using its client ID and secret. Once you have the credentials, you can use a library like `octokit` to interact with the GitHub API in Node.js. Install it using:

npm install @octokit/rest

• After installation, set up Octokit to include the authentication token generated from your GitHub App. This ensures secure communication with the GitHub API.

const { Octokit } = require("@octokit/rest");

const octokit = new Octokit({
  auth: `your_github_token`
});

Create a Check Run

• To manage Continuous Integration (CI) checks, you'll start by creating a check run. A check run refers to a single CI process that contributes to the final results of a check suite. Define the repository owner, repo, and commit SHA where the check run will be performed.

const createCheckRun = async () => {
  try {
    const response = await octokit.checks.create({
      owner: 'repo-owner',
      repo: 'repo-name',
      name: 'Test Check Run',
      head_sha: 'commit-sha',
      status: 'in_progress'
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};
createCheckRun();

Update a Check Run

• Once a check run is set up, you'll likely want to update it based on your CI results. The status can be completed and include the conclusion such as success, failure, or neutral.

const updateCheckRun = async (checkRunId) => {
  try {
    const response = await octokit.checks.update({
      owner: 'repo-owner',
      repo: 'repo-name',
      check_run_id: checkRunId,
      status: 'completed',
      conclusion: 'success', // or 'failure', 'neutral'
      output: {
        title: 'CI Results',
        summary: 'Integration tests passed successfully!',
        text: 'Detailed text can be added here.'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};
updateCheckRun('check-run-id');

Retrieve Check Run Results

• At times, you might need to fetch and inspect the results of past check runs for analytics or reporting. This will require retrieving check runs for a specific ref or SHA.

const listCheckRuns = async () => {
  try {
    const response = await octokit.checks.listForRef({
      owner: 'repo-owner',
      repo: 'repo-name',
      ref: 'commit-sha'
    });
    console.log(response.data.check_runs);
  } catch (error) {
    console.error(error);
  }
};
listCheckRuns();

Webhooks for CI Automation

• Leverage GitHub webhooks to automate CI integrations. You'll need to set up listeners for events like check\_run, which indicates when a check run is created, completed, or requested. Node.js can handle these webhooks using libraries such as `express`:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
  const { action, check_run } = req.body;

  if (action === 'completed') {
    console.log(`Check run completed with conclusion: ${check_run.conclusion}`);
  }
  res.sendStatus(200);
});

app.listen(3000, () => {
  console.log('Server is listening on port 3000');
});

• Make sure your server is publicly accessible to GitHub so it can send webhook requests to your `/webhook` endpoint.