Setup

Add health reporting to your CI pipeline and optionally connect Slack for automated delivery. For a minimal walkthrough, see Quick Start.

Create a project and API key

If you haven’t already, create a Dev Herald project and generate an API key. Add it 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 POSTs everything to Dev Herald in one step.

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 ingest.

Ingest via API

Most teams use the dev-herald/health GitHub Action, which handles collection and upload automatically. If you need to POST signals yourself — from a custom CI runner or another orchestrator — use the health ingest endpoint documented in the API Reference.

Authenticate with your project API key (Bearer token). The report is associated with the project for that key; no repository name is required in the body.

Action inputs

Input	Required	Description
`api-key`	✅	Your Dev Herald project API key
`knip-report-path`	No	Path to a Knip JSON report for unused code signals
`lockfile-path`	No	Path to `pnpm-lock.yaml` or `package-lock.json` for dependency and CVE signals
`workflow-run-url`	No	Link to the CI run — shown in Slack summaries
`cve-detail`	No	Set to `"true"` to include per-advisory CVE details

Next steps

Review available Signals
Set up a Weekly Slack Report