11 KiB
11 KiB
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: Active development. Phase 3F (ActivityPub federation) complete. Phase 4 (AI diagnostics + signed artifacts) is next.
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 (admin-only, filterable) | Done |
| Workspaces (multi-tenant namespaces) | 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 |
|---|---|
| NATS event bus + WebSocket live push | Done |
| CI orchestrator (DAG pipeline execution) | Done |
| Runner manager (Docker backend) | Done |
| Build artifact storage + download | Done |
| Pipeline cancellation + job retry | Done |
| Pipeline log streaming (per-step, NATS) | Done |
| Pipeline DAG visualization (frontend) | Done |
| Dashboard CI command center | Done |
| Pipeline log viewer (collapsible, per-step) | Done |
| Kubernetes / Firecracker runner backends | Planned (Phase 2D) |
| Matrix builds + reusable workflow templates | Planned |
| Flaky test detection | Planned |
Environments + GitOps
| Feature | Status |
|---|---|
| Environment model + deployment tracking | Done |
| Deployment status lifecycle API | Done |
| Unified operational timeline | Done |
| Secret management (Global → Workspace → Repo → Env) | Done |
| GitOps controller (drift detection + auto-sync) | Done |
| Deployment promotion workflows | Planned (Phase 4) |
| Rollback visualization | Planned (Phase 4) |
| Canary / blue-green support | Planned (Phase 4) |
Observability + Security
| Feature | Status |
|---|---|
GET /health — structured DB + NATS liveness check |
Done |
GET /metrics — Prometheus endpoint (HTTP + platform metrics) |
Done |
| HTTP instrumentation middleware (latency histogram, request counter) | Done |
Per-repo operational health summary (GET /repos/.../health) |
Done |
| NATS-driven pipeline + deployment counters | Done |
| Health sparklines in repo/env pages (frontend) | Planned (Phase 4) |
| Secret scanning | Planned (Phase 4) |
| Dependency scanning | Planned (Phase 4) |
| Signed artifacts (Sigstore/Cosign) | Planned (Phase 4) |
Federation
| Feature | Status |
|---|---|
| ActivityPub actor model | Done |
WebFinger (/.well-known/webfinger) |
Done |
Actor documents (/users/{username}) |
Done |
| Inbox (receive + HTTP signature verify) | Done |
| Outbox (OrderedCollection, paginated) | Done |
| Followers / Following collections | Done |
| HTTP signatures (draft-cavage-http-signatures) | Done |
| Follow / Accept auto-accept flow | Done |
| RSA-2048 key pair lazy generation | Done |
| Cross-instance pull requests (ForgeFed) | Planned (Phase 4) |
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.
Docker note: CI execution requires the Docker daemon to be running. If Docker is unavailable, the runner manager logs a warning and disables CI; the rest of the platform works normally.
Architecture
ForgeBucket
├── API Gateway (Chi router — internal/api/router.go)
├── 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 — internal/api/handlers/)
├── CI Orchestrator (DAG execution, Docker runner — internal/domain/ci/)
├── GitOps Controller (drift detection, auto-sync — internal/domain/gitops/)
├── Observability (Prometheus metrics, health — internal/observability/)
├── Environment Service (environments, deployments — internal/api/handlers/environment.go)
├── Secret Manager (scoped AES-256-GCM — internal/api/handlers/secret.go)
├── Workspace Service (multi-tenant namespaces — internal/api/handlers/workspace.go)
├── Event Bus (NATS core, NoOp fallback — internal/events/)
├── Audit Log (every mutating request — internal/api/middleware/audit.go)
├── Federation Layer (ActivityPub inbox/outbox, HTTP signatures — internal/domain/federation/)
├── Database (PostgreSQL + XORM — internal/models/)
└── Web Frontend (React 18 + TypeScript, //go:embed — web/)
Middleware chain (every request):
Logger → RealIP → Recoverer → Metrics → CORS → CSRF → SessionAuth → AuditLog → Handler
Tech Stack
| Layer | Technology |
|---|---|
| Language | Go 1.21+ |
| Router | Chi |
| ORM / Migrations | XORM + PostgreSQL |
| Event bus | NATS core (github.com/nats-io/nats.go) |
| Real-time | WebSockets (nhooyr.io/websocket) |
| CI execution | Docker (docker run --rm via exec.Command) |
| Frontend framework | React 18 + TypeScript |
| Build tool | Vite |
| Styling | Tailwind CSS v4 |
| YAML parsing | gopkg.in/yaml.v3 (workflow definitions) |
| Code editing | CodeMirror |
| Container | Docker Compose (dev) |
| Federation | ActivityPub / ForgeFed (WebFinger, actor, inbox/outbox, HTTP signatures) |
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 |
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 |
ARTIFACT_ROOT |
No | Artifact storage path, defaults to ../artifacts relative to REPO_ROOT |
NATS_URL |
No | NATS connection URL (e.g. nats://localhost:4222). If unset, event bus is no-op |
GITOPS_RECONCILE_INTERVAL |
No | Seconds between periodic drift checks, default 300. 0 disables the ticker |
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 | Done |
| Phase 3C | Workspaces + secret management hierarchy (Global → Workspace → Repo → Env) | Done |
| Phase 3D | GitOps controller + drift detection + auto-sync | Done |
| Phase 3E | Observability (Prometheus /metrics, structured /health, repo health API) |
Done |
| Phase 3F | Federation handlers (ActivityPub WebFinger, actor, inbox/outbox, HTTP signatures) | Done |
| Phase 4 | AI diagnostics, signed artifacts, OCI registry, secret/dep scanning | Next |
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.