Documentation

Everything you need to understand, deploy, and customize Sentinel for your open-source workflow.

Overview

What Sentinel does and why it exists

Sentinel tracks activity across open source repositories and turns it into a clean, queryable feed. Built for contributors and maintainers who want fast awareness of issues, pull requests, reviews, releases, and discussions without living inside GitHub tabs.

Polls repositories

Monitors GitHub events on a scheduled interval

Stores events

Normalizes and saves to Postgres for fast queries

Serves data

Exposes clean API endpoints for consumption

Modern dashboard

Next.js UI with filters and activity views

Architecture

How the system works end-to-end

GitHub API → Worker → Postgres → API → Next.js UI
  1. 1
    Backend worker reads a configured list of repositories
  2. 2
    Calls GitHub Events API for each repository on a schedule
  3. 3
    Events are normalized into typed payloads and stored in Postgres
  4. 4
    Frontend fetches latest events via API and renders activity view

Project Structure

backend-worker/

Event ingestion worker, Prisma schema, and database migrations

site/

Next.js frontend, UI components, and dashboard views

Quick Start

Get Sentinel running locally in minutes

1. Backend Worker

Prerequisites

  • Node.js 18+ (or 20+)
  • PostgreSQL database
  • GitHub token (recommended for higher rate limits)

Installation

cd backend-worker
pnpm install

# Create .env file
DATABASE_URL="postgres://USER:PASSWORD@HOST:PORT/DB?sslmo   de=require"
GITHUB_TOKEN="your_github_token"
REPO_LIST="open-metadata/openmetadata,OWASP-BLT/BLT"
POLL_INTERVAL_MS="300000"
REQUEST_DELAY_MS="200"

# Run migrations
pnpm prisma generate
pnpm prisma migrate deploy

# Start worker
pnpm dev

2. Frontend Dashboard

Installation

cd site
npm install

# Optional: Configure API endpoint
EVENTS_API_URL="http://localhost:8080/api/events/open-metadata/openmetadata"

# Start development server
npm run dev

Configuration

Environment variables and settings

VariableDescriptionRequired
DATABASE_URLPostgres connection string used by Prisma
Yes
GITHUB_TOKENGitHub API token to increase rate limits
Recommended
REPO_LISTComma-separated repository list (owner/repo format)
Yes
POLL_INTERVAL_MSWorker poll interval in milliseconds
Optional
REQUEST_DELAY_MSDelay between API calls to reduce rate spikes
Optional
EVENTS_API_URLAPI endpoint used by the frontend
Optional

API Reference

Expected response format and endpoints

Event Response Schema

{
  "success": true,
  "message": "Events fetched successfully",
  "data": [
    {
      "id": "...",
      "org": "open-metadata",
      "repo": "openmetadata",
      "username": "...",
      "avatar": "...",
      "type": "IssueCommentEvent",
      "createdAt": "2026-02-03T11:26:54.000Z",
      "updatedAt": null,
      "data": { "type": "IssueCommentEvent" },
      "isSensitive": false
    }
  ]
}

Make It Your Own

Customize Sentinel for your specific needs

Repository List Configuration

The worker supports a simple comma-separated list using the REPO_LIST environment variable:

REPO_LIST="owner1/repo1,owner2/repo2"

For a hard-coded list, replace the env-driven configuration in backend-worker/src/index.ts:

export const repoList = [
  { owner: "OWASP-BLT", repo: "BLT" },
  { owner: "open-metadata", repo: "openmetadata" }
];

Customize Polling Interval

Adjust POLL_INTERVAL_MS based on your rate limit and update frequency needs. Default is 5 minutes (300000ms).

Extend Event Types

Modify the Prisma schema and worker logic to track additional GitHub event types beyond the current set of issues, PRs, releases, and comments.

Contributing

Help improve Sentinel

Contributions are welcome! Here's how to get started:

  1. 1
    Fork the repository and create a new branch from main
  2. 2
    Make your changes with a clear, focused scope
  3. 3
    Test locally to ensure everything runs correctly
  4. 4
    Open a pull request with a short, clear summary

Code Standards

  • Keep changes small and focused
  • Use simple, clear naming conventions
  • Avoid large refactors in a single PR
  • Keep UI changes accessible and readable
  • Add screenshots for UI changes

For detailed contribution guidelines, see CONTRIBUTING.md

Resources

Helpful links and references

GitHub Repository

View source code and contribute

Contribution Guide

Learn how to contribute

Issue Tracker

Report bugs or request features

Live Dashboard

See Sentinel in action

Need Help?

If you have questions or run into issues, open a GitHub issue or start a discussion.

Open an IssueStart a Discussion