8.0 KiB
8.0 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: Early development. Core Git hosting, collaboration, and auth are functional. CI/CD and GitOps integrations are 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 |
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 (model + routes) |
| Repository RBAC (read/write/admin) | Done |
CI/CD
| Feature | Status |
|---|---|
| Pipeline DAG visualization | In progress |
| CI orchestrator | Planned (Phase 2) |
| Runner manager | Planned (Phase 2) |
| Artifact registry | Planned (Phase 2) |
| Forgejo Actions integration (gRPC) | Planned (Phase 2) |
| Flaky test detection | Planned (Phase 2) |
GitOps + Environments
| Feature | Status |
|---|---|
| GitOps controller | Planned (Phase 3) |
| Environment management | Planned (Phase 3) |
| Drift detection | Planned (Phase 3) |
| Deployment promotion workflows | Planned (Phase 3) |
| Rollback visualization | Planned (Phase 3) |
| Canary / blue-green support | Planned (Phase 3) |
Observability + Security
| Feature | Status |
|---|---|
| Unified operational timeline | Planned (Phase 3) |
| Secret scanning | Planned (Phase 3) |
| Dependency scanning | Planned (Phase 3) |
| Signed artifacts (Sigstore/Cosign) | Planned (Phase 4) |
| Audit log | Planned (Phase 3) |
Federation
| Feature | Status |
|---|---|
| ActivityPub actor model | Done (data layer) |
| Federation handlers / inbox / outbox | Planned (Phase 3) |
| Cross-instance pull requests | Planned (Phase 3) |
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
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.
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/)
├── Federation Layer (ActivityPub actors — internal/domain/federation/) ← stub
├── CI Orchestrator (pipeline scheduling — internal/domain/ci/) ← 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 → Handler
Tech Stack
| Layer | Technology |
|---|---|
| Language | Go 1.21+ |
| Router | Chi |
| ORM / Migrations | XORM + PostgreSQL |
| Frontend framework | React 18 + TypeScript |
| Build tool | Vite |
| Styling | Tailwind CSS v4 |
| Code editing | CodeMirror |
| Real-time | WebSockets |
| Container | Docker Compose (dev) |
| Federation | ActivityPub / ForgeFed |
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 |
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 |
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 via Docker Compose |
Roadmap
| Phase | Focus | Status |
|---|---|---|
| Phase 1 | Core Git hosting, auth, PRs, issues, RBAC, design system | Done |
| Phase 2 | CI/CD orchestrator, runner manager, pipeline visualization, artifact registry | In progress |
| Phase 3 | GitOps controller, environments, observability, federation handlers, audit log | Planned |
| Phase 4 | Command palette, AI diagnostics, signed artifacts, package registry | 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.