@omni-comment/core

Combine outputs from many jobs into a single comment

Usage

Create a file named omni-comment.yml to define the section IDs that can appear in the comment.

sections:
  - test_results
  - deploy_preview
  - perf_stats

Now, import and call the omniComment function to create or update the comment.

import { omniComment } from "@omni-comment/core"

await omniComment({
  message: "Hello world",
  issueNumber: 123,
  section: "test_results",
  token: "github_token",
})

Options

| Name | Description | Required | Default | | ------------- | ---------------------------------------------------------------- | -------- | ------------------ | | token | GitHub auth token | ✅ | | | repo | The repository where to create the comment | ✅ | | | issueNumber | The issue number where to create the comment | ✅ | | | section | The section ID that matches with the value in omni-comment.yml | ✅ | | | message | Comment body | | | | title | An optional title for the comment | | | | collapsed | Whether the comment should be collapsed by default | | false | | logger | A custom logger to use | | | | configPath | Path to the config file | | omni-comment.yml |

Metadata (omni-comment.yml)

| Name | Description | Required | | ---------- | -------------------------------------------------------------------------- | -------- | | sections | A list of section IDs that defines the order of comment sections | ✅ | | title | An optional title for the comment | | | intro | An optional introduction for the comment that is displayed under the title | |

How does it work?

I built this library to solve a problem we have at Ramp of lots of CI outputs that each need to post back to the PR via comments. The problem is, the more comments you have, the more noisy it gets.

The idea was, what if you had a single comment that contained everything? Test results, deploy preview URLs, warnings, etc. When you try to build that though, there are some challenges.

First, it should support workflows running in parallel, so the order in which the comments are posted is non deterministic. However, we want the order of sections in the comment to be consistent between runs. Additionally, we need to support updating the comment if you push a new commit, and the test results are now passing instead of failed.

The GitHub issue comments API only supports sending a complete comment body when making updates, so if we just get the current value and send it back with our updates, its possible that two separate jobs update the comment at the same time and one of the updates will be lost. To workaround this, we need a way for jobs to acquire a "lock" on the issue, so that they can safely get the current comment value, make edits, and push the updated value back to GitHub.

What better locking mechanism than reactions! Turns out, the create reaction API will return a 201 Created status when a reaction is newly created and a 200 OK when the reaction already exists. Using this subtle API detail, this action will attempt to acquire a lock by creating the reaction and waiting for a 201 status code. If it receives a 200 status code, it will sleep and retry until it is able to acquire a lock (it will fail after 30 seconds if it fails to acquire a lock). Once the lock is acquired, the existing comment will be downloaded, edited, and pushed back to GitHub. After updating the comment, the lock is released by deleting the reaction.

Simple right? 😉