Getting started

Quick start

Run a local scan to see affected flows and reviewer checks before opening a pull request.

git clone https://github.com/MergeSignal/mergesignal.git
cd mergesignal
pnpm install

pnpm ms scan

Locally you will see upgrade findings, affected entrypoints, and reviewer checks in the terminal. More options (JSON export, failing a job above a threshold) are in the repository README.

For deeper insights and automated pull request comments, continue below.

GitHub Actions (CI)

Add a short workflow so every qualifying pull request runs MergeSignal in GitHub Actions and writes upgrade findings to the workflow Summary.

name: MergeSignal
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  analysis:
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: MergeSignal/mergesignal/.github/actions/merge-signal-scan@main
        with:
          scan_profile: trusted
          engine_repo_token: ${{ secrets.MERGESIGNAL_ENGINE_REPO_TOKEN }}

To automatically comment on pull requests via the MergeSignal GitHub App, webhook, and API configuration, see the GitHub App section below.

Web app

The MergeSignal web app shows upgrade findings, affected application flows, reviewer guidance, and scan history per repository.

GitHub App

Optional: connect a GitHub App to your hosted API so repository events (for example lockfile changes on pull requests) can enqueue scans-useful when you want ingestion aligned with your deployment, not only GitHub Actions.

What you get

The MergeSignal GitHub App lets your hosted MergeSignal API receive repository events. When a lockfile changes on a pull request or push, MergeSignal can enqueue a scan so results stay fresh without relying on Actions alone-useful when you want ingestion and PR automation aligned with your deployment.

When to use this page

You already run or plan to run MergeSignal’s API (hosted or self-managed) and want GitHub-driven scans and optional PR feedback wired to that stack. This is optional and assumes you are comfortable with GitHub App permissions and API configuration.

Prerequisites

• A running MergeSignal API reachable from GitHub (HTTPS).
• Ability to create a GitHub App in your org or account and install it on target repositories.

Setup

1. In GitHub, create a GitHub App (org-owned is fine).
2. Set the webhook URL to your API’s webhook path-for example https://<your-api-host>/github/webhook (use the host where apps/api is deployed).
3. Create a webhook secret and keep it for API configuration.
4. Subscribe to Pull request and Push events.
5. Under Repository permissions, match how you use GitHub:
   • Contents: Read-only so MergeSignal can read lockfiles from the repository.
   • Pull requests: Read-only is enough for webhook-driven scans (list PR files, read lockfiles). Use Read & write only if MergeSignal should also write on the pull request on GitHub (for example comments).
   • Checks: use Read & write when you want scan status on the pull request Checks tab (GitHub Check Runs). If results only live in MergeSignal, leave Checks unset or read-only. Without Read & write, Check Run calls return “Resource not accessible by integration”.
   • Issues: Read & write only when the features you enable need that scope (for example certain comment paths on GitHub).
6. Install the App on the repositories (or all repos) that should send events.
7. If you later change permissions on the App, each installation must accept the update: in GitHub, open Settings → GitHub Apps (or Organization settings → Installed GitHub Apps), choose Configure for this App, and complete Review request until the banner clears. Until then, new tokens do not include added scopes.
8. On the API, set GITHUB_APP_ID, GITHUB_PRIVATE_KEY (PEM; newlines may be escaped as \n in env), and GITHUB_WEBHOOK_SECRET to match the App.

On pull request events (opened, reopened, synchronize), MergeSignal looks for lockfile changes at the PR head and enqueues a scan when appropriate. On push, it does the same for the pushed commits. Supported lockfiles include pnpm-lock.yaml, package-lock.json, and yarn.lock (including nested paths).

What happens next

Scans surface in the MergeSignal web app and API like any other run. If you have not yet added GitHub Actions summaries for every PR, complete GitHub Actions first, then return here when you are ready to wire the App to your API.

For a local full stack (Docker, databases, migrations), see the local development guide in the repository — not this product doc page.