Quick Start

Get health reports running in your CI pipeline in minutes.

Create an account at dev-herald.com and connect your GitHub account.

Create a project and API key

Create a new project for your GitHub repository
Generate an API key for the project
Add the API key to your GitHub repository secrets as DEV_HERALD_API_KEY

The same API key works for both PR comments and health reports.

Add a health workflow

Create a workflow file at .github/workflows/health.yml:


name: Health
 
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9:00 UTC
  workflow_dispatch:
 
jobs:
  health:
    runs-on: ubuntu-latest
    timeout-minutes: 15
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
          cache-dependency-path: pnpm-lock.yaml
 
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
 
      - name: Run Knip
        run: >-
          pnpm exec knip --reporter json --reporter compact --no-exit-code
          | { IFS= read -r l; printf '%s\n' "$l" > results.json; cat; }
 
      - name: Upload health data
        uses: dev-herald/health@v1
        with:
          api-key: ${{ secrets.DEV_HERALD_API_KEY }}
          knip-report-path: results.json
          workflow-run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          lockfile-path: ${{ github.workspace }}/pnpm-lock.yaml
          cve-detail: "false"

The dev-herald/health action collects dependency counts, bundle metrics, unused code (via Knip), and optional CVE data from your lockfile — then uploads everything to Dev Herald in one step.

Trigger the workflow manually from the Actions tab to send your first report, then view it in the Dev Herald dashboard.

Connect Slack (optional)

To receive reports in Slack:

Go to Organization Settings → Slack in the Dev Herald dashboard
Install the Dev Herald bot to your Slack workspace
In Slack, mention @Dev Herald in a channel and choose Subscribe this channel for your project

Reports are posted automatically after each successful CI run.

Next steps

Review Signals to understand what each metric means
See Setup for action inputs and advanced configuration
Set up a Weekly Slack Report

For direct API usage, see the API Reference.