CLI and dashboard to fetch and monitor Dependabot alerts for GitHub repositories, users, or organizations.
- Fetch Dependabot alerts for a single repository, a user, or an organization.
- Cache results in a local SQLite database for offline access and history tracking.
- Filter alerts by date (
--since). - Output results in readable text format or JSON for integration with other tools.
- Support for including forked repositories.
- Web dashboard with trend charts, MTTR metrics, SLA tracking, and cross-repo analytics.
- Automatic daily refresh of all tracked repos via built-in cron scheduler.
- Interactive API documentation via Swagger UI at
/docs. - Fix plan advisor: grouped fix recommendations by package, severity, and ecosystem.
- Docker-ready for server deployment.
gh-monit uses the GitHub REST API directly via Octokit. Authentication is resolved in this order:
GITHUB_TOKENenvironment variable (recommended for servers and Docker)gh auth tokenfallback — if the GitHub CLI is installed and authenticated, the token is read automatically (convenient for local development)
- Classic PAT:
repo+security_eventsscopes - Fine-grained PAT: Repository access with Dependabot alerts (read) and Metadata (read) permissions
-
Clone the repository:
git clone <repository-url> cd gh-monit
-
Install dependencies:
npm install
-
Build the project:
npm run build
# Development
npm run dev -- dependabot [options]
# Production (after build)
gh-monit dependabot [options]Fetch Dependabot alerts for a repo, user, or organization.
Options:
--repo <owner/name>: Specify a single GitHub repository (e.g.,facebook/react).--user <username>: Fetch alerts for all repositories owned by a user.--org <org>: Fetch alerts for all repositories in an organization.--include-forks: Include forked repositories when fetching for a user or org (default:false).--db <path>: Path to the SQLite database file (default:~/.gh-monit/gh-monit.db).--since <date>: Filter alerts updated since the specified ISO date (e.g.,2023-01-01).--json: Output the results in JSON format.--refresh: Bypass the cache and force a fresh fetch from the GitHub API.
Show grouped fix recommendations for Dependabot alerts. Groups alerts by package, severity, and ecosystem, and shows the patched version to update to.
Options:
--repo <owner/name>: Show fix plan for a specific repo (default: all tracked repos).--db <path>: Path to the SQLite database file (default:~/.gh-monit/gh-monit.db).--json: Output the results in JSON format.
# Fix plan for all tracked repos
gh-monit fix-plan
# Fix plan for a specific repo
gh-monit fix-plan --repo owner/repo
# JSON output for scripting
gh-monit fix-plan --repo owner/repo --jsonThe fix plan is also available in the dashboard:
- Repo detail view — click a repo, then the Fix Plan tab
- Analytics — the Fix Plan sub-tab shows cross-repo recommendations
Start the web dashboard to browse alerts visually.
Options:
--port <number>: Port to listen on (default:3847).--no-open: Skip opening the browser automatically.--db <path>: Path to the SQLite database file.
# Monitor a specific repository
npm run dev -- dependabot --repo owner/repo --refresh
# Monitor all repositories for a user
npm run dev -- dependabot --user your-username
# Monitor an organization and include forks
npm run dev -- dependabot --org my-org --include-forks
# Get alerts updated since a specific date in JSON format
npm run dev -- dependabot --user your-username --since 2023-10-01 --json
# Start the dashboard
npm run dev -- dashboard# Set your GitHub token in a .env file (see .env.example)
echo "GITHUB_TOKEN=ghp_your_token_here" > .env
# Build and start
docker compose up -d
# View logs
docker compose logs -fThe dashboard will be available at http://localhost:3847.
Data is persisted in a Docker volume (gh-monit-data), so it survives container restarts.
Set GH_MONIT_USER and/or GH_MONIT_ORG in your .env file. On first startup, if the database is empty, the dashboard will automatically fetch all repos and their alerts in the background:
GITHUB_TOKEN=ghp_your_token_here
GH_MONIT_USER=your-username
GH_MONIT_ORG=your-org
Both variables support comma-separated values for multiple users/orgs (e.g., GH_MONIT_ORG=org1,org2).
You can also populate data manually using docker exec:
# Fetch all repos for a GitHub user
docker exec gh-monit-server-1 node dist/index.js dependabot --user your-username --db /data/gh-monit.db --refresh
# Fetch all repos for an organization
docker exec gh-monit-server-1 node dist/index.js dependabot --org my-org --db /data/gh-monit.db --refresh
# Fetch a single repo
docker exec gh-monit-server-1 node dist/index.js dependabot --repo owner/repo --db /data/gh-monit.db --refreshOnce populated, you can refresh individual repos from the dashboard UI or via the API:
# Refresh a single repo
curl -X POST http://localhost:3847/api/repos/owner/repo/refresh
# Refresh all tracked repos
curl -X POST http://localhost:3847/api/repos/refresh-allThe dashboard exposes a REST API. Interactive documentation is available at /docs (Swagger UI) once the server is running:
http://localhost:3847/docs
The raw OpenAPI 3.0 spec is also served at /api/openapi.json, which can be imported into tools like Postman or Insomnia.
Endpoint groups:
| Group | Endpoints |
|---|---|
| Dashboard | GET /api/summary, GET /api/repos |
| Repos | GET /api/repos/:owner/:name/alerts, POST /api/repos/:owner/:name/refresh, DELETE /api/repos/:owner/:name |
| Bulk refresh | POST /api/repos/refresh-all (SSE stream) |
| History | GET /api/history/trends, GET /api/history/mttr, GET /api/history/sla, GET /api/repos/:owner/:name/history |
| Analytics | GET /api/analytics/vulnerabilities, GET /api/analytics/dependencies, GET /api/analytics/ecosystems |
| Fix Advisor | GET /api/fix-advisor, GET /api/repos/:owner/:name/fix-advisor |
| Setup | GET /api/setup/status, GET /api/setup/repos, POST /api/setup/initialize, POST /api/setup/reset |
| Scheduler | GET /api/scheduler |
docker build -t gh-monit .
docker run -d \
--name gh-monit \
-p 3847:3847 \
-e GITHUB_TOKEN=ghp_your_token_here \
-v gh-monit-data:/data \
gh-monit| Variable | Description | Default |
|---|---|---|
GITHUB_TOKEN |
GitHub personal access token (required) | — |
GH_MONIT_USER |
GitHub username(s) to auto-seed on first startup (comma-separated) | — |
GH_MONIT_ORG |
GitHub org(s) to auto-seed on first startup (comma-separated) | — |
GH_MONIT_DB_PATH |
Path to the SQLite database file | /data/gh-monit.db (Docker) or ~/.gh-monit/gh-monit.db (local) |
GH_MONIT_REFRESH_SCHEDULE |
Cron expression for auto-refresh schedule | 0 6 * * * (daily at 6:00 AM) |
The dashboard includes a built-in cron scheduler that automatically refreshes all tracked repos on a configurable schedule. By default, it runs daily at 6:00 AM.
Configure the schedule via the GH_MONIT_REFRESH_SCHEDULE environment variable using standard cron syntax:
# Every 6 hours
GH_MONIT_REFRESH_SCHEDULE="0 */6 * * *"
# Twice daily at 8am and 8pm
GH_MONIT_REFRESH_SCHEDULE="0 8,20 * * *"
# Every Monday at midnight
GH_MONIT_REFRESH_SCHEDULE="0 0 * * 1"The scheduler staggers API calls with a 2-second delay between repos to stay within GitHub rate limits. If a refresh cycle is still running when the next one is scheduled, it will be skipped.
Check the scheduler status via the API:
curl http://localhost:3847/api/schedulerThe CLI interacts with the GitHub REST API to retrieve Dependabot alerts. To avoid hitting API rate limits excessively and to provide faster subsequent access, it stores the alerts in a local SQLite database.
- First Run: The CLI fetches all alerts from GitHub and stores them in the database.
- Subsequent Runs: It can use the cached data. Use the
--refreshflag to force an update from GitHub. - Database: The database tracks the sync state and history of alerts.
npm run dev: Run the CLI in development mode usingtsx.npm run build: Build both the dashboard and CLI for production.npm run build:cli: Build only the CLI backend.npm run build:dashboard: Build only the dashboard frontend.npm run lint: Type-check the codebase.
- Node.js 22+
- A GitHub token (via
GITHUB_TOKENenv var orgh auth login)