PR Beacon 🗼

A Danger.js-inspired GitHub Action that maintains a single sticky PR comment consolidating CI failures, warnings, and messages from across all your workflow jobs.

Overview

PR Beacon solves the noise problem in pull request CI feedback. Instead of each job posting its own comment — leaving a cluttered thread — every job contributes to one persistent beacon comment that is created on first run and updated in place on every subsequent run.

The beacon is structured into two main areas:

• Tables — Three severity levels displayed as structured HTML tables at the top of the comment: | Section | Default Icon | Meaning | |---|---|---| | Fails | 🚫 | Blocking issues that must be resolved | | Warnings | ⚠️ | Non-blocking issues worth attention | | Messages | 📖 | Informational notes |

• Markdowns — Free-form markdown sections appended below the tables.

Each job owns its content slice via a content ID (defaulting to workflow/job). On every run a job replaces only its own slice, leaving other jobs' content untouched. Concurrent writes from parallel jobs are handled with optimistic locking and automatic retries.

Features

• Sticky comment — one comment per PR, updated in place, never duplicated
• Multi-job safe — parallel CI jobs can all write without clobbering each other
• Upsert semantics — each job replaces only its own previously written content
• Markdown support — render markdown inside table cells or in free-form sections
• Custom icons — override the default icon per row
• JSON file input — pass a structured payload file for complex multi-row updates
• SDK — use the @balvajs/pr-beacon NPM package directly in your own scripts

GitHub Action Usage

Minimal — single message

- uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    message: Build completed successfully.

Report a failure

- uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    fail: Tests failed on Node 22. See the [logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).

Report a warning

- uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    warn: Bundle size increased by 12 kB.
    warn-icon: 📦

Multi-row payload via JSON file

For complex scenarios — multiple rows, mixed severity levels, or markdown sections — write the payload to a JSON file and point the action at it.

beacon-payload.json

{
  "fails": [{ "message": "Coverage dropped below 80%.", "id": "coverage-check" }],
  "warnings": [
    "Dependency `lodash` has a known vulnerability.",
    { "message": "Build took **4 m 12 s** — consider caching.", "icon": "🐢" }
  ],
  "messages": ["Deployed preview to https://preview.example.com"],
  "markdowns": [
    {
      "id": "coverage-report",
      "message": "## Coverage\n\n| File | % |\n|---|---|\n| index.ts | 94% |\n| utils.ts | 78% |"
    }
  ]
}

- name: Generate payload
  run: node scripts/generate-beacon-payload.js > beacon-payload.json

- uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    json-file: beacon-payload.json

Multi-job workflow

Each job writes to its own content slice. The beacon accumulates content from all jobs.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
        continue-on-error: true
      - uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
        if: always()
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fail: Unit tests failed. # written under ID "{workflow} / {job}"

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint
        continue-on-error: true
      - uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
        if: always()
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          warn: Lint warnings detected. # written under ID "{workflow} / {job}"

Post a markdown section

- uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    markdown-id: coverage-report
    markdown: |
      ## Coverage

      | File | % |
      |---|---|
      | index.ts | 94% |
      | utils.ts | 78% |

Targeted update — replace content from a previous job

Use content-ids-to-update to remove content written by a specific earlier job before adding new content. This is useful in retry or follow-up jobs.

- uses: Balvajs/pr-beacon@1248b5b89c25f915cc9e65b8dcc99c2e7be8f973 # v1.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    content-ids-to-update: 'CI / build'
    message: Build retried and passed.

Inputs

| Input | Required | Default | Description | | ----------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | token | Yes | — | GitHub token (GITHUB_TOKEN) used to post PR comments. Requires issues: write and pull-requests: write permissions. | | json-file | No | '' | Path to a JSON file defining the full beacon payload (see schema). | | fail | No | '' | A single failure message added to the Fails table. Supports markdown. | | fail-icon | No | '' | Custom icon for the fail entry (e.g. 💥). | | fail-id | No | '' | Content ID for the fail entry, used for targeted upsert. | | warn | No | '' | A single warning message added to the Warnings table. Supports markdown. | | warn-icon | No | '' | Custom icon for the warn entry. | | warn-id | No | '' | Content ID for the warn entry, used for targeted upsert. | | message | No | '' | A single informational message added to the Messages table. Supports markdown. | | message-icon | No | '' | Custom icon for the message entry. | | message-id | No | '' | Content ID for the message entry, used for targeted upsert. | | markdown | No | '' | A single free-form markdown block appended below the tables. | | markdown-id | No | '' | Content ID for the markdown entry, used for targeted upsert. | | content-ids-to-update | No | '' | Comma-separated list of content IDs to remove before adding new content. | | fail-on-fail-message | No | 'false' | When 'true', the action step exits with a non-zero code if any fail message is present. |

JSON file schema

{
  "fails":    [ "string" | { "message": "string", "icon?": "string", "id?": "string" } ],
  "warnings": [ "string" | { "message": "string", "icon?": "string", "id?": "string" } ],
  "messages": [ "string" | { "message": "string", "icon?": "string", "id?": "string" } ],
  "markdowns": [ "string" | { "message": "string", "id?": "string" } ],
  "options": {
    "contentIdsToUpdate?": [ "string" ]
  }
}

Permissions

Add the following permissions to your workflow or job:

permissions:
  issues: write
  pull-requests: write

SDK

The @balvajs/pr-beacon package exposes the same engine used by the GitHub Action, letting you build the beacon programmatically in your own Node.js scripts.

Installation

npm install @balvajs/pr-beacon

Requirements: Node.js ≥ 24, must be run inside a GitHub Actions environment with GITHUB_TOKEN set.

submitPrBeacon(callback, options?)

The primary entry point. Runs your callback, then submits the accumulated content to the PR comment in one atomic operation.

import { submitPrBeacon } from '@balvajs/pr-beacon';

await submitPrBeacon(async (beacon) => {
  beacon.fail('Tests failed on Node 22.');
  beacon.warn('Bundle size increased by 12 kB.', { icon: '📦' });
  beacon.message('Preview deployed to https://preview.example.com');
  beacon.markdown('coverage', '## Coverage\n\n94% overall.');
});

Callback argument — PrBeacon

| Method | Signature | Description | | ----------------- | ----------------------------- | ------------------------------------------------------------------------ | | fail | (message, options?) => void | Add a row to the Fails table. | | warn | (message, options?) => void | Add a row to the Warnings table. | | message | (message, options?) => void | Add a row to the Messages table. | | markdown | (message, options?) => void | Append a free-form markdown section. | | hasFails | () => boolean | Returns true if any fail was added. | | getPrInfo | () => Promise<PrInfo> | Fetch pull request metadata (title, head SHA, base/head branches, etc.). | | getChangedFiles | () => Promise<File[]> | Fetch the full list of files changed in the PR. |

Row methods accept an optional second argument:

type RowOptions = {
  icon?: string; // override the default section icon
  id?: string; // content ID for targeted upsert (default: "workflow/job")
  markdownToHtml?: boolean; // convert markdown syntax in the message to HTML
};

submitPrBeacon options

type Options = {
  githubToken?: string; // defaults to process.env.GITHUB_TOKEN
  contentIdsToUpdate?: string[]; // content IDs to clear before writing (default: ["workflow/job"])
  shouldFailOnFailMessage?: boolean; // call setFailed() when fails are present
};

Advanced — accessing PR info

import { submitPrBeacon } from '@balvajs/pr-beacon';

await submitPrBeacon(async (beacon) => {
  const pr = await beacon.getPrInfo();
  const files = await beacon.getChangedFiles();

  const hasDbMigration = files.some((f) => f.filename.startsWith('db/migrations/'));

  if (hasDbMigration) {
    beacon.warn(
      `This PR modifies **${files.filter((f) => f.filename.startsWith('db/migrations/')).length}** database migration(s). Please review carefully.`,
      { icon: '🗄️', markdownToHtml: true },
    );
  }

  beacon.message(`PR #${pr.number}: _${pr.title}_`, { markdownToHtml: true });
});

Advanced — multi-job with custom content IDs

import { submitPrBeacon } from '@balvajs/pr-beacon';

await submitPrBeacon(
  (beacon) => {
    beacon.fail('E2E tests failed on Chrome.');
  },
  {
    contentIdsToUpdate: ['e2e-chrome'],
    shouldFailOnFailMessage: true,
  },
);

License

MIT © Balvajs