ForgeBucket
A unified operating system for software delivery — not just a Git host.
ForgeBucket is a self-hosted, federated developer operations platform. Where other Git platforms show you a list of files, ForgeBucket surfaces deployments, pipeline health, environment drift, and operational context directly alongside your code. Repositories are runtime systems. The dashboard is a command center.
Status: Phase 2C in progress. CI/CD execution backend is fully operational. Pipeline visualization and dashboard integration are being wired up now.
What Makes It Different
| Principle | What it means |
|---|---|
| Repositories are runtime systems | Repo pages show deployments, environments, health, and risk — not just a file tree |
| Operational awareness by default | Failing pipelines, stale PRs, security alerts, and environment drift surface without digging |
| GitOps is first-class | Git is the source of truth for deployment state, rollbacks, and environment promotion |
| Keyboard-first UX | Global command palette, minimal navigation depth, low cognitive load |
| Federated by design | ActivityPub (ForgeFed) for cross-instance pull requests and collaboration |
| Sovereign | Fully self-hostable — your code, your infrastructure, your keys |
Feature Status
Core Platform
| Feature | Status |
|---|---|
| User auth (registration, login, sessions) | Done |
| CSRF + session security | Done |
| SSH key management | Done |
| OIDC / OAuth2 (optional) | Done |
| Access tokens (scoped, expiring) | Done |
| Deploy keys | Done |
| Audit log | Done |
Git Hosting
| Feature | Status |
|---|---|
| Smart HTTP transport (clone/push/pull) | Done |
AGit protocol (refs/for/ PR creation) |
Done |
| Branch management | Done |
| Commit + diff viewing | Done |
| Git LFS (per-repo, configurable size limits) | Done |
| Branch protection rules | Done |
Collaboration
| Feature | Status |
|---|---|
| Pull requests (open/merged/closed) | Done |
| Issues | Done |
| Code review (inline comments, mobile bottom-sheet) | Done |
| Side-by-side + unified diff viewer | Done |
| Reviewer assignment | Done |
| Merge strategies (merge/squash/rebase) | Done |
| Webhooks | Done |
| Repository RBAC (read/write/admin) | Done |
CI/CD
| Feature | Status |
|---|---|
| CI orchestrator (DAG pipeline execution) | Done (Phase 2B) |
| Runner manager (Docker backend) | Done (Phase 2B) |
| Build artifact storage | Done (Phase 2B) |
| Pipeline cancellation + job retry | Done (Phase 2B) |
| NATS event bus + WebSocket live push | Done (Phase 2A) |
| Pipeline DAG visualization (frontend) | Done (Phase 2C) |
| Dashboard CI command center | Done (Phase 2C) |
| Pipeline log viewer (per-step, collapsible) | Done (Phase 2C) |
| Kubernetes / Firecracker runner backends | Planned (Phase 2D) |
| Forgejo Actions gRPC integration | Planned |
| Matrix builds + reusable workflow templates | Planned |
| Flaky test detection | Planned |
GitOps + Environments
| Feature | Status |
|---|---|
| Environment model + deployment tracking | In progress (Phase 3A) |
| Unified operational timeline | Planned (Phase 3B) |
| Secret management hierarchy | Planned (Phase 3C) |
| GitOps controller + drift detection | Planned (Phase 3D) |
| Deployment promotion workflows | Planned (Phase 3D) |
| Rollback visualization | Planned (Phase 3D) |
| Canary / blue-green support | Planned (Phase 3D) |
Observability + Security
| Feature | Status |
|---|---|
| Prometheus endpoint + health sparklines | Planned (Phase 3E) |
| Secret scanning | Planned (Phase 4) |
| Dependency scanning | Planned (Phase 4) |
| Signed artifacts (Sigstore/Cosign) | Planned (Phase 4) |
Federation
| Feature | Status |
|---|---|
| ActivityPub actor model | Done (data layer) |
| Federation handlers / inbox / outbox | Planned (Phase 3F) |
| Cross-instance pull requests | Planned (Phase 3F) |
Quick Start
# 1. Clone and configure
git clone https://github.com/forgeo/forgebucket.git
cd forgebucket
cp .env.example .env # fill in SESSION_SECRET and CSRF_SECRET
# 2. Start PostgreSQL + NATS
make docker-up
# 3. Run DB migrations
make migrate
# 4. Start both servers (Go :8080 + Vite :5173)
make dev
The Go API runs at http://localhost:8080. The Vite dev server runs at http://localhost:5173 and proxies API requests.
Local dev note:
DATABASE_URLmust uselocalhost(notpostgres) andNATS_URLmust be set tonats://localhost:4222. The.envfile ships with correct defaults for local development. See.env.examplefor all variables.
Architecture
ForgeBucket
├── API Gateway (Chi router, internal/api/)
├── Auth Service (sessions, CSRF, OIDC — internal/api/handlers/)
├── Repository Service (git HTTP, branches, LFS — internal/domain/git/)
├── Pull Request Service (PRs, reviews, merge — internal/api/handlers/)
├── Issue Service (issues, labels — internal/api/handlers/)
├── CI Orchestrator (DAG execution, Docker runner — internal/domain/ci/) ← Phase 2B done
├── Event Bus (NATS core, NoOp fallback — internal/events/) ← Phase 2A done
├── Federation Layer (ActivityPub actors — internal/domain/federation/) ← Phase 3F stub
├── Secret Manager (env-based, scoped tokens — internal/config/)
├── Database (PostgreSQL + XORM — internal/models/)
└── Web Frontend (React 18 + TypeScript, embedded via //go:embed — web/)
Middleware chain (every request):
Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → AuditLog → Handler
Tech Stack
| Layer | Technology |
|---|---|
| Language | Go 1.21+ |
| Router | Chi |
| ORM / Migrations | XORM + PostgreSQL |
| Event bus | NATS (core; JetStream planned for Phase 2B durability) |
| Real-time | WebSockets (nhooyr.io/websocket) |
| CI execution | Docker (docker run --rm) |
| Frontend framework | React 18 + TypeScript |
| Build tool | Vite |
| Styling | Tailwind CSS v4 |
| Code editing | CodeMirror |
| Container | Docker Compose (dev) |
| Federation | ActivityPub / ForgeFed (data layer only) |
Design System
ForgeBucket has its own design language — intentionally distinct from GitHub and GitLab.
Philosophy: information-dense but calm. Inspired by Linear, Datadog, and VS Code — not enterprise CRUD forms.
- Colors: Semantic token palette with full dark/light mode. Brand blue
#0052CC(light) /#3B82F6(dark). Source of truth:frontend/src/ui/tokens.ts - Grid: 8px base unit. All spacing is multiples of 4px (xs) or 8px (sm). No arbitrary pixel values.
- Touch targets: 44px minimum on all interactive elements (WCAG 2.5.5)
- Navigation: Triple-state sidebar (expanded 320px / collapsed 56px / mobile bottom bar). Keyboard-first.
- Breakpoints: Desktop 1440px, mobile 375px. Mobile code review uses bottom-sheet overlays, not modals.
- Typography: System font stack (Segoe UI, Roboto, sans-serif)
Environment Variables
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection string — use localhost for local dev |
SESSION_SECRET |
Yes | Session signing key, ≥ 32 chars (openssl rand -hex 32) |
CSRF_SECRET |
Yes | CSRF key, exactly 32 chars (openssl rand -hex 16) |
PORT |
No | HTTP port, default 8080 |
REPO_ROOT |
Yes | Absolute path for bare git repository storage |
NATS_URL |
No | NATS connection URL (e.g. nats://localhost:4222). If unset, CI runs in no-op mode |
INSTANCE_URL |
Yes | Public URL of this instance (no trailing slash) |
INSTANCE_NAME |
No | Display name, default ForgeBucket |
OIDC_ISSUER |
No | OIDC provider URL |
OIDC_CLIENT_ID |
No | OIDC client ID |
OIDC_CLIENT_SECRET |
No | OIDC client secret |
DEBUG |
No | Disables Secure cookies, enables verbose logging, proxies frontend to Vite |
Common Commands
| Command | What it does |
|---|---|
make dev |
Start Go API + Vite dev server concurrently |
make build |
Build frontend, embed into Go binary |
make migrate |
Sync XORM schemas to PostgreSQL |
make test |
Run Go tests + Vitest |
make lint |
go vet + ESLint |
make docker-up |
Start PostgreSQL + NATS via Docker Compose |
Roadmap
| Phase | Focus | Status |
|---|---|---|
| Phase 1 | Core Git hosting, auth, PRs, issues, RBAC, design system | Done |
| Phase 2A | NATS event bus, WebSocket hub, audit log | Done |
| Phase 2B | CI orchestrator, runner manager, Docker backend, artifact registry | Done |
| Phase 2C | Pipeline DAG visualization, dashboard CI upgrade, command palette | Done |
| Phase 3A | Environment model + deployment tracking | Done |
| Phase 3B | Unified operational timeline | In progress |
| Phase 3C–F | Secrets, drift detection, federation, observability | Planned |
| Phase 4 | AI diagnostics, signed artifacts, OCI registry, dep scanning | Planned |
Contributing
See AGENTS.md for AI-assisted development conventions, architecture boundaries, and what not to build without discussion.
All UI contributions must be tested at both 1440px desktop and 375px mobile. Spacing must use tokens from frontend/src/ui/tokens.ts — no arbitrary pixel values.
Module Path
github.com/forgeo/forgebucket
License
MIT License. See LICENSE for details.