Skip to content

README.md

Latest commit

 

History

History
109 lines (77 loc) · 3.23 KB

README.md

File metadata and controls

109 lines (77 loc) · 3.23 KB

GitHub Pulse

GitHub Pulse is an internal engineering dashboard that aggregates GitHub activity across your organization's repositories. It gives teams visibility into pull requests, contributor metrics, and delivery health — with optional Jira integration to surface ticket quality and epic progress alongside code activity.

Features

  • Dashboard — PR activity, merge rates, review throughput, and contributor stats across tracked repositories
  • Jira Integration — View epics and stories, AI-powered ticket quality scoring, and acceptance criteria improvement suggestions
  • Sync Management — Configure sync schedules, trigger manual syncs, and inspect sync history
  • Bot Filter — Suppress bot-generated PRs from metrics
  • Configuration — Manage GitHub tokens, tracked repositories, team members, and Jira connection settings

Technology Stack

Layer Technology
Frontend React 19, TypeScript, Vite, Tailwind CSS 4, shadcn/ui, Recharts, TanStack Query
Backend Java 21, Spring Boot 3.3, Spring Data JPA
Database PostgreSQL 16, Flyway migrations
AI Anthropic Claude (ticket quality analysis)
Testing Cucumber (BDD integration tests)
Scheduling ShedLock (distributed cron)
Packaging Docker, Docker Compose

Prerequisites

  • Java 21+
  • Node.js 20+
  • Docker (for PostgreSQL)
  • A GitHub Personal Access Token with repo and read:org scopes

Environment Variables

Copy .env.example to .env and fill in your values:

cp .env.example .env
Variable Required Description
GITHUB_TOKEN Yes GitHub PAT with repo and read:org scopes
ANTHROPIC_API_KEY No Enables AI ticket quality analysis in Jira view

Database connection defaults (DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, DB_PASSWORD) are pre-configured for the Docker Compose stack and do not need to be set for local development.

Running Locally

Option 1 — Dev mode (recommended, frontend HMR on :3000)

make start-dev

Option 2 — Production-like (single server on :8080)

make start

Option 3 — Docker Compose (full containerized stack)

docker compose up -d --build

Stopping

make stop

Building

Build a production JAR with the frontend embedded:

make build

The artifact is written to backend/target/github-pulse-*.jar.

Running Tests

cd backend && ./mvnw test

Tests use Cucumber BDD scenarios covering the dashboard, settings, team management, repository management, and sync workflows.

Project Structure

github-pulse/
├── backend/                  # Spring Boot application
│   ├── src/main/java/        # Controllers, services, repositories, domain
│   └── src/test/java/        # Cucumber step definitions and runners
├── frontend/                 # React + Vite SPA
│   └── src/pages/            # Dashboard, Config, Jira, Sync, Admin
├── operations/
│   └── database/             # Flyway SQL migrations
├── docker-compose.yml
└── Makefile                  # Dev lifecycle commands