GitHub & repo triggers
Audit on every push and pull request. Pick the hosted GitHub App for zero-config checks, or run the GitHub Action in your own workflow.
Which one?
| GitHub App | GitHub Action | |
|---|---|---|
| Setup | Install the app, select repos | Add a workflow file + API key secret |
| Triggers | Push, pull request, weekly re-audit, user schedules | Any GitHub Actions event |
| Result | Check Run + PR comment with a new-findings delta | Step summary, optional SARIF, exit code |
| Availability | Private beta — see the runbook below | Available now from the public action repo |
Both paths consume your monthly audit quota and write to the same audit history, so you can switch between them without losing results.
GitHub App (private beta)
The hosted app watches the branches you connect, enqueues the full audit pipeline on every push, and posts a Check Run. Pull requests get a delta audit: only findings that are new versus the base branch can fail the check, so existing debt never blocks unrelated work.
What it does
- Push audit on the connected branch (default branch on install).
- Pull-request audit on
openedandsynchronize, with a PR comment listing new and fixed findings. - Check Run annotation for each blocking finding (file + line, capped at 50).
- Weekly re-audit of repos with no pushes for 7 days, so CVEs and dependency rot still surface.
- Optional user schedules: weekly or monthly, per plugin or per repo.
Rules
Settings → Repositories controls each connection:
- Auto-audit — pause push/PR triggers without disconnecting.
- Branch — the branch audited on push (PRs audit their own head).
- Fail on — CRITICAL, HIGH (default), MEDIUM, LOW or informational only. The gate applies to both the push Check Run and the PR delta.
A Check Run only blocks a merge when it is required
In GitHub, open Settings → Branches → branch protection and add WP HealthKit Security Audit as a required status check. Without that, the check is informational.
Self-host / operator runbook
The hosted app is not publicly listed yet. To run it against your own deployment:
- Create a GitHub App (Settings → Developer settings → GitHub Apps). Homepage: your app URL. Callback:
/api/github/callback. - Permissions: Contents (read), Checks (write), Pull requests (write), Metadata (read). Events: Push and Pull request.
- Webhook URL:
https://your-domain/api/github/webhook. Generate a secret. - Set
GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEYandGITHUB_APP_WEBHOOK_SECRETon the web + processor services. - Set
NEXT_PUBLIC_GITHUB_APP_NAMEto the app slug. Until it resolves publicly, the settings UI hides the install button. - Install the app on a repo. The callback registers each accessible repo with auto-audit on.
- Push a commit, then confirm the Check Run appears and the audit lands in the dashboard.
- Add the check to branch protection if you want it to block merges.
Quota is claimed before the audit is queued and refunded if enqueue or processing fails. A repo whose owner is out of quota is skipped, never partially audited.
GitHub Action
The action is published from BuiltByGo/wp-healthkit-action. It packages the plugin, runs a full audit, writes SARIF for code scanning, and fails the step at your chosen severity.
name: Plugin Audit
on:
pull_request:
paths:
- "**/*.php"
- "**/composer.json"
- "**/composer.lock"
permissions:
contents: read
pull-requests: write
security-events: write
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: BuiltByGo/wp-healthkit-action@v1
id: audit
with:
api-key: ${{ secrets.WP_HEALTHKIT_API_KEY }}
fail-on: HIGH
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: wphk-audit.sarif
category: wp-healthkit| Input | Default | Notes |
|---|---|---|
api-key | required | Platform or Enterprise key. Store it as a repository secret. |
plugin-path | . | Directory of the plugin — point at a subfolder in a monorepo. |
fail-on | HIGH | CRITICAL, HIGH, MEDIUM, LOW or none. |
sarif | true | Writes wphk-audit.sarif in the workspace. |
api-url | wphealthkit.com | Override for self-hosted or staging. |
Add paths: filters so docs-only PRs do not burn quota. The action exports report-url, overall-risk, findings-count, critical-count and high-count for later steps.
Troubleshooting
The check never appears. Confirm the app is installed on that repo, the push branch matches the connected branch, and auto-audit is on. Repos with no quota are skipped.
Existing findings fail every PR. PR checks only gate new findings. If the base branch has never been audited, run one push audit first so the delta has a baseline.
A merge still goes through. Mark the check as required in branch protection; GitHub does not block on informational checks.
Action fails with 401/429. 401 means the API key secret is missing or revoked. 429 means the monthly quota is exhausted — add path filters or upgrade.
Start with the Action
It works today, on any plan with API access, and needs one workflow file.