274 lines
11 KiB
Markdown
274 lines
11 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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](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.
|