forge-dashboard

README

forge-dashboard

A dashboard of open pull requests, issues, and CI status across every repository you have write access to on GitHub and a Forgejo instance — one page instead of two forge UIs. It has passwordless login and per-user tokens.

Quick start

Generate the encryption key once and keep it somewhere safe, such as a password manager. It needs openssl; any base64-encoded 32 random bytes work too.

export ENCRYPTION_KEY="$(openssl rand -base64 32)"
docker run --rm -p 8080:8080 -v forge-dashboard-data:/data \
  -e RP_ID=localhost -e RP_ORIGIN=http://localhost:8080 \
  -e ENCRYPTION_KEY \
  ghcr.io/alrayyes/forge-dashboard:latest

Open http://localhost:8080, register a passkey, then add your GitHub and Forgejo credentials from Settings. On the next run, export the same key again: a new one can't decrypt the credentials saved in the volume. The full command with hardening flags, building from source and the health check are in Running it.

RP_ID and RP_ORIGIN default to localhost and http://localhost:8080. For any other deployment, set them to your real domain and its https:// origin; see Configuration.

Page	Light	Dark
Branches. The CI status of every default branch, latest commit first.
Pull requests. Open pull requests across both forges, with CI status, filters, and sorting.
Pull request details. A pull request's description, comments, and thumbs reactions.
Phone sheet. The same details on a 360px screen.
Pipeline checks. A pull request's checks with state, time and failure excerpt, from its CI pill.
Issues. Open issues across both forges.
Releases. Release pull requests waiting to ship.
Release details. The release notes a release pull request publishes.
Bots. Dependabot and Renovate pull requests.
Bot details. A bot pull request, its generated text collapsed.
Insights. Charts of CI state and the busiest repos.
Webhooks. Which tracked repos have a confirmed webhook, and a way to add one.
Settings. Four groups, one at a time: display, connections, behaviour, integrations and security.
Login. Passkey sign-in.

Fixture data, not a real account's actual repositories. The release workflow regenerates every screenshot on each release (see scripts/capture-screenshots.ts), so they're never more than one release stale.

Requirements

• Go 1.27 or newer, to build.
• bun, to build from source — bun run build:web has to run before go build picks up its output (see Architecture). Not needed to run a pre-built release binary or the Docker image, both of which already have that step baked in.
• A passkey-capable browser to sign in at all — any current Chrome, Safari, Firefox or Edge; a phone counts too. Nothing else to install.
• Somewhere writable for the database (DB_PATH, default /data/forge-dashboard.db) that survives a restart — registered passkeys, sessions, and every user's encrypted forge credentials live there. In Docker that means a mounted volume at /data; see Docker.
• ENCRYPTION_KEY, a base64-encoded 32-byte key the process refuses to start without — see Configuration for how to generate one. It's what encrypts every user's forge tokens at rest; there's no sensible default for a secret like this one.
• Each signed-in user configures their own forge credentials from the Settings page after registering — see Credentials for exactly which permissions to grant. Nothing forge-related needs setting before the process starts.

Documentation

• Pull request actions: what a row offers, and why a blocked action is blocked.
• Pull request pages: the details pop-up, the Releases and Bots pages and hiding one pull request.
• Issues: the issues page and the settings that hide issues.
• Main branches: the default-branch CI page and GET /api/main-branches.
• Live updates and filters: how the board refreshes, when rows wait before they land, the first load after a restart, the navigation counts, and how filters are offered, remembered and folded on a phone.
• API: the HTTP endpoints, the OpenAPI contract and the MCP endpoint.
• Rate limits: why a forge is rate limited, what the dashboard does meanwhile, and what to change.
• Accounts: passkey login, API tokens and the GitHub and Forgejo credentials.
• Configuration: every environment variable, how repositories are discovered and the GitHub App option.
• Running it: building and starting the app, and running the Docker image with its health check.
• Deployment: where the project's own instance runs.
• The changelog page: the page the footer version links to.
• Webhooks: registering the forge webhook and the checks the dashboard runs on its own.
• Error pages: the app's own 404 and 500 pages and what they show.
• Reports: the test, coverage and Lighthouse reports published after every green push to main.
• Architecture: the design choices behind the app, from passkey login to the MCP endpoint and the single binary.

Contributing

See CONTRIBUTING.md for the toolchain, the hooks, and how a change gets reviewed and released. ARCHITECTURE.md is the one-page map of how the pieces fit, and the decision records record why the big choices went the way they did.

Licence

AGPL-3.0. Chosen over the plain GPL-3.0 this project started under because AGPL's network-use clause also covers running a modified copy as a hosted service, which GPL alone doesn't.

Fonts

The app serves its own fonts, so a page never contacts another host to render text. IBM Plex Sans (400, 500, 600, 700) and IBM Plex Mono (400, 500, 600) come from the pinned @fontsource/ibm-plex-sans and @fontsource/ibm-plex-mono packages, bundled by the web build in the Latin and Latin Extended subsets, with font-display: swap. IBM Plex is released under OFL-1.1, the SIL open font licence, which allows bundling and redistribution with this app.