HomeLab/ForgeBucket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

implemented agents, readme, and changelog md files for ai-assisted

Browse Source 
development.
This commit is contained in:
erangel1
2026-05-11 19:22:11 +02:00
parent 6d5122bc11
commit db0f402ab2
4 changed files with 1232 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+201 -71
View File
@@ -1,101 +1,231 @@
# ForgeBucket 🛡️🪣
# ForgeBucket
**Sovereign Federation meets Enterprise Design.**
> A unified operating system for software delivery — not just a Git host.
ForgeBucket is a production-ready, federated git collaboration platform. It combines the high-performance, lightweight Go engine of **Forgejo** with the sophisticated, high-density UI/UX of **Bitbucket**, optimized for a "Responsive-First, Access Anywhere" experience.
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.
---
## 🚀 The Vision
## What Makes It Different
ForgeBucket aims to provide developers with a world-class code review and project management experience without sacrificing data sovereignty. It bridges the gap between community-driven open-source software and enterprise-grade usability.
- **Engine:** Built on the Forgejo/Gitea ecosystem.
- **Interface:** Powered by Atlassian Design System (ADS) principles.
- **Connectivity:** Full ActivityPub (ForgeFed) integration for a decentralized git world.
| 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 |
---
## 🛠️ Tech Stack
## Feature Status
### Backend & Core
### 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 |
- **Language:** Go (Golang) 1.21+
- **Database:** PostgreSQL with XORM
- **Git Engine:** Native System Git Binary execution
- **CI/CD:** Forgejo Actions (gRPC protocol)
### 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 |
### Frontend & UX
### 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 |
- **Framework:** React 18+ (Embedded in Go binary)
- **Styling:** Tailwind CSS + Atlassian Design Tokens
- **Components:** Custom implementation of Atlaskit primitives
- **Real-time:** WebSockets for live logs and notifications
### 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) |
---
## ✨ Key Features
- **Responsive Navigation:** A triple-state sidebar (Expanded, Collapsed, Mobile Bottom-Bar) that adheres to an 8px grid system.
- **Advanced Diff Viewer:** Side-by-side and unified views with "Bottom Sheet" comment overlays for mobile code reviews.
- **Federated Pull Requests:** Interaction across different ForgeBucket/Forgejo instances via ActivityPub.
- **AGit "Quick Edit":** Web-based file editing with automatic `refs/for/` branch creation for instant PRs.
- **Skeleton Loading:** Optimized "Perceived Performance" using pulsate loading states for metadata.
---
## 🔒 Security & Compliance
- **OWASP Top 10 Compliance:** Strict protection against XSS, CSRF, and SQLi.
- **Command Sanitization:** Hardened wrapper for all Git binary executions.
- **Identity:** OIDC and OAuth2 support with Row-Level Security (RLS) mentalities.
- **Auditability:** Full logging of all administrative and git-over-HTTP actions.
---
## 🏁 Getting Started
### Prerequisites
- Go 1.21 or higher
- Node.js 18+ (for frontend development)
- PostgreSQL 14+
- System Git 2.20+
### Installation
1. **Clone the repository:**
## Quick Start
```bash
git clone [https://github.com/your-repo/forgebucket.git](https://github.com/your-repo/forgebucket.git)
cd forgebucket
# 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
```
2. **Setup Frontend:**
The Go API runs at `http://localhost:8080`. The Vite dev server runs at `http://localhost:5173` and proxies API requests.
```Bash
cd frontend
npm install
npm run build
---
## 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/)
```
3. **Build the Binary:**
```Bash
cd ..
go build -o forgebucket main.go
**Middleware chain (every request):**
```
Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
```
4. **Run:**
---
```Bash
./forgebucket web
```
## Tech Stack
## 🤝 Contributing
| 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 |
We follow the "Responsive-First" contribution model. Please ensure all UI changes are tested on both Desktop (1440px) and Mobile (375px) breakpoints.
---
## 📄 License
## Design System
This project is licensed under the MIT License - see the LICENSE file for details. Portions of the code are derived from Forgejo (GPLv3).
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](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.