GitHub Integrations
Fetch repository statistics, issues, and pull requests synced from the VeriWorkly repository.
Description
VeriWorkly is built in the open. The GitHub API module serves metrics that a background job syncs from the official VeriWorkly repository into our own database — reads never call GitHub at request time.
By routing these requests through our backend rather than fetching them directly from the client, we achieve three critical benefits:
- Zero Client-Side Rate Limiting: Users never hit GitHub's restrictive unauthenticated API limits.
- Token Security: GitHub Personal Access Tokens (PATs) remain safely isolated on the server.
- Blazing Fast Responses: Data is served directly from our database/Redis cache rather than waiting on upstream network requests.
Sync Architecture & Latency
Data is not fetched in real-time on every GET request. Instead, we use a background polling mechanism to maintain system health:
- Automated Sync: A background worker (
runGithubSyncOnce.ts) runs on a cron schedule to poll GitHub and update our internal database. - Latency Expectation: Because of this caching layer, newly opened issues or merged PRs may take a short time to reflect on the VeriWorkly dashboard.
- Resilience: If GitHub experiences an outage, this API will gracefully fall back to serving the last known cached state.
Authentication & Access
| Method | Endpoint | Access Level | Requirement |
|---|---|---|---|
GET | /stats, /issues | No session | An API key with the github:read scope, or a first-party origin. |
POST | /admin/sync | Admin | A session cookie whose email matches the configured ADMIN_EMAIL. |
POST /github/admin/sync is strictly protected and cannot be reached with an API key — it
requires an admin session. A request with no session returns 401 Unauthorized; an authenticated
non-admin returns 403 Forbidden.
The read endpoints still need credentials
/github/stats and /github/issues require no logged-in user, but they are not open to anonymous
callers: a request carrying neither an API key nor a whitelisted first-party Origin/Referer is
rejected with 401.
Available Endpoints
GET /github/stats— Fetch Repository StatsGET /github/issues— List Issues & PRsPOST /github/admin/sync— Trigger Manual Sync (admin only)
Get Changelog Entry by IDGET
Fetch a single changelog entry by its id. Requires the `changelog:read` scope when called with an API key.
Get GitHub StatsGET
Fetch aggregated issue and pull-request statistics for the configured repository, as of the last sync. Served from the last synced snapshot, not live from GitHub — `syncedAt` tells you how fresh it is. Cached for 12 hours. This endpoint has no user session of its own: call it with an API key holding the `github:read` scope, or from a whitelisted first-party origin. A request with neither is rejected with `401`.