proxmox/docs/04-configuration/GITEA_ORG_STRUCTURE.md

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 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 and Gitea setup
• AS4_411_PHOENIX_SUBMODULE_AND_PUSH_ALL.md — Sankofa marketplace
• Gitea Organizations
• Gitea Labels