140 lines
4.5 KiB
Markdown
140 lines
4.5 KiB
Markdown
# Gitea Organizational Structure and Conventions
|
|
|
|
**Last Updated:** 2026-02-10
|
|
**Status:** Active Documentation
|
|
**Gitea Instance:** https://gitea.d-bis.org
|
|
**Primary Org:** d-bis
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
Gitea uses a flat model: **Organization → Teams → Users**. This document defines conventions for virtual hierarchy via labels, team naming, and repository organization to support flexible structuring beyond the built-in flat model.
|
|
|
|
---
|
|
|
|
## 2. Label-Based Virtual Hierarchy (Option A)
|
|
|
|
Use repository labels to create virtual groups without code changes.
|
|
|
|
### 2.1 Project Labels
|
|
|
|
| Label | Purpose | Example Repos |
|
|
|-------|---------|---------------|
|
|
| `project/sankofa` | Sankofa Phoenix platform and marketplace | sankofa, as4-411 |
|
|
| `project/omnis` | OMNIS application | omnis |
|
|
| `project/proxmox` | Proxmox infrastructure and docs | proxmox |
|
|
| `project/dbis_core` | DBIS core libraries and services | dbis_core |
|
|
| `project/chain138` | Chain 138 blockchain (Besu, RPC, etc.) | smom-dbis-138, rpc-translator-138 |
|
|
| `project/explorer` | Blockscout, explorers | explorer-monorepo |
|
|
| `project/miracles_in_motion` | MIM web and API | miracles_in_motion |
|
|
| `project/the_order` | Order service | the_order |
|
|
| `project/virtual-banker` | Virtual banker (voice/TTS, widget) | virtual-banker |
|
|
|
|
### 2.2 Domain Labels
|
|
|
|
| Label | Purpose | Example Repos |
|
|
|-------|---------|---------------|
|
|
| `domain/blockchain` | Blockchain, smart contracts, RPC | smom-dbis-138, alltra-lifi-settlement |
|
|
| `domain/web` | Web apps, portals, frontends | miracles_in_motion, omnis |
|
|
| `domain/infrastructure` | Proxmox, scripts, configs | proxmox, smom-dbis-138-proxmox |
|
|
| `domain/api` | Backend APIs | dbis_core, the_order |
|
|
|
|
### 2.3 Label Format Convention
|
|
|
|
- **Project labels:** `project/<name>` — groups repos by product/project
|
|
- **Domain labels:** `domain/<name>` — groups repos by technical domain
|
|
- Use lowercase, hyphens for multi-word: `project/sankofa-phoenix`
|
|
|
|
### 2.4 Applying Labels
|
|
|
|
1. **Create org-level labels:** Run `GITEA_TOKEN=xxx bash scripts/dev-vm/apply-gitea-labels.sh` (includes `project/virtual-banker`).
|
|
2. Repo Settings → Labels — add relevant `project/*` and `domain/*` labels to each repo (e.g. **virtual-banker**: `project/virtual-banker`, `domain/api`).
|
|
3. Filter repos by label in Gitea UI or API
|
|
|
|
---
|
|
|
|
## 3. Team Naming Conventions
|
|
|
|
### 3.1 Format
|
|
|
|
`org-d-bis/team-<role>` or `org-d-bis/team-<project>-<role>`
|
|
|
|
### 3.2 Example Teams
|
|
|
|
| Team Name | Purpose |
|
|
|-----------|---------|
|
|
| `team-frontend` | Frontend developers |
|
|
| `team-backend` | Backend developers |
|
|
| `team-infra` | Infrastructure, DevOps |
|
|
| `team-sankofa` | Sankofa/Phoenix maintainers |
|
|
| `team-blockchain` | Chain 138, Besu, RPC maintainers |
|
|
|
|
### 3.3 Permissions
|
|
|
|
- **Owners:** Full org control
|
|
- **Admins:** Repo admin, branch protection
|
|
- **Writers:** Push, PR merge
|
|
- **Readers:** Pull, read-only
|
|
|
|
---
|
|
|
|
## 4. Target Hierarchy (Design)
|
|
|
|
Planned virtual structure for filtering and reporting:
|
|
|
|
```
|
|
d-bis (org)
|
|
├── project/sankofa
|
|
│ ├── sankofa (main repo)
|
|
│ └── as4-411 (marketplace submodule)
|
|
├── project/omnis
|
|
│ └── omnis
|
|
├── project/proxmox
|
|
│ └── proxmox
|
|
├── project/chain138
|
|
│ ├── smom-dbis-138
|
|
│ ├── rpc-translator-138
|
|
│ └── smom-dbis-138-proxmox
|
|
├── project/explorer
|
|
│ └── explorer-monorepo
|
|
├── project/virtual-banker
|
|
│ └── virtual-banker
|
|
└── domain/*
|
|
└── (repos tagged by domain)
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Option B: Multiple Orgs (Medium Term)
|
|
|
|
If separation is needed:
|
|
|
|
| Org | Purpose | Repos |
|
|
|-----|---------|-------|
|
|
| `d-bis` | Main, shared | proxmox, dbis_core |
|
|
| `d-bis-sankofa` | Sankofa Phoenix | sankofa, as4-411 |
|
|
| `d-bis-infra` | Infrastructure | smom-dbis-138-proxmox, configs |
|
|
| `d-bis-apps` | Applications | omnis, miracles_in_motion, the_order |
|
|
|
|
Requires Keycloak/SAML/LDAP for cross-org identity.
|
|
|
|
---
|
|
|
|
## 6. Option C: Subgroups (Long Term)
|
|
|
|
Track Forgejo/Gitea PR [#35295](https://github.com/go-gitea/gitea/pull/35295) for native subgroups. Target hierarchy:
|
|
|
|
- `d-bis / sankofa / marketplace`
|
|
- `d-bis / blockchain / chain138`
|
|
- `d-bis / apps / omnis`
|
|
|
|
---
|
|
|
|
## 7. References
|
|
|
|
- [DEV_VM_GITOPS_PLAN.md](DEV_VM_GITOPS_PLAN.md) — Dev VM and Gitea setup
|
|
- [AS4_411_PHOENIX_SUBMODULE_AND_PUSH_ALL.md](AS4_411_PHOENIX_SUBMODULE_AND_PUSH_ALL.md) — Sankofa marketplace
|
|
- [Gitea Organizations](https://docs.gitea.com/usage/organizations)
|
|
- [Gitea Labels](https://docs.gitea.com/usage/labels)
|