From 19c30cfa514d490231c76d48bed5564e89d1dfec Mon Sep 17 00:00:00 2001 From: Stephan Lo Date: Sun, 29 Jun 2025 16:54:29 +0200 Subject: [PATCH] doc(forgejo): WiP ... added forgejo documentation for 2nd level operation --- .../local-development-onboarding.md} | 0 .../admin-cli-commands.md | 35 +++++++++++ .../organisations.md | 62 ++++++++++++++++++ ...gamnisation-team-entity-model-large-2.puml | 57 +++++++++++++++++ ...gamnisation-team-entity-model-large-3.puml | 63 +++++++++++++++++++ ...orgamnisation-team-entity-model-large.puml | 62 ++++++++++++++++++ ...nisation-team-entity-model-small copy.puml | 56 +++++++++++++++++ .../user-onboarding/user-onbording-flow.puml | 31 +++++++++ 8 files changed, 366 insertions(+) rename docs/technical-documentation/product/components/forgejo/{onboarding-local-development.md => local-development/local-development-onboarding.md} (100%) create mode 100644 docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/admin-cli-commands.md create mode 100644 docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/organisations.md create mode 100644 docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-2.puml create mode 100644 docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-3.puml create mode 100644 docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large.puml create mode 100644 docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-small copy.puml create mode 100644 docs/technical-documentation/product/components/forgejo/user-onboarding/user-onbording-flow.puml diff --git a/docs/technical-documentation/product/components/forgejo/onboarding-local-development.md b/docs/technical-documentation/product/components/forgejo/local-development/local-development-onboarding.md similarity index 100% rename from docs/technical-documentation/product/components/forgejo/onboarding-local-development.md rename to docs/technical-documentation/product/components/forgejo/local-development/local-development-onboarding.md diff --git a/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/admin-cli-commands.md b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/admin-cli-commands.md new file mode 100644 index 0000000..660cae6 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/admin-cli-commands.md @@ -0,0 +1,35 @@ + +create user with simple password which doesn't need to be changed: + +forgejo admin user create --username user-8 --email user-8@u.de --password p --must-change-password=false + + +create admin token in forgejo-instance with forgejo admin + + +410880a9c760:/var/lib/gitea$ forgejo admin user generate-access-token --username admin2 --token-name "automation-token4" --scopes write:admin,write:repository,write:organization,write:user,write:issue,write:misc +Access token was successfully created: d7497188e767ec44bfa06424e25cc7d2387399a0 + +add logn to tea + +tea login add --url http://localhost:3000 --token d7497188e767ec44bfa06424e25cc7d2387399a0 --name myadmin + + +login to myadmin + + +❯ tea login +┌────────────────┬───────────────────────┬────────────────┬──────────┬─────────┐ +│ NAME │ URL │ SSH HOST │ USER │ DEFAULT │ +├────────────────┼───────────────────────┼────────────────┼──────────┼─────────┤ +│ localhost:3000 │ http://localhost:3000 │ localhost:3000 │ admin2 │ false │ +│ admin │ http://localhost:3000 │ localhost:3000 │ johannes │ false │ +│ myadmin │ http://localhost:3000 │ localhost:3000 │ admin2 │ false │ +└────────────────┴───────────────────────┴────────────────┴──────────┴─────────┘ +❯ tea login myadmin + + myadmin + + @admin2 http://localhost:3000/admin2 + + Created: 29 Jun 25 12:39 CEST \ No newline at end of file diff --git a/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/organisations.md b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/organisations.md new file mode 100644 index 0000000..d16b2c3 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/organisations.md @@ -0,0 +1,62 @@ +Das `owners`-Team in Gitea/Forgejo ist **etwas Besonderes** und tatsächlich **hardcoded** – hier sind die Details: + +--- + +## 🧠 Bedeutung des `owners` Teams + +### 🟩 Es ist **automatisch vorhanden** + +* Jede Organisation hat immer ein Team namens `owners`. +* Dieses Team wird **automatisch erstellt**, wenn die Organisation erstellt wird. + +### 🔐 Es hat **immer Admin-Rechte** + +* Mitglieder des `owners`-Teams haben **volle Admin-Rechte** auf: + + * alle Repositories der Organisation + * alle Teams + * die Organisation selbst (z. B. Mitgliederverwaltung, Einstellungen) +* Rechte können **nicht reduziert** oder **entfernt** werden. +* Nur Mitglieder dieses Teams können: + + * neue Teams erstellen oder löschen + * andere Mitglieder zum `owners`-Team hinzufügen oder entfernen + +### 🔒 Sicherheitsrelevant + +* Dieses Team steuert **letztlich die Kontrolle über die gesamte Organisation**. +* Es ist vergleichbar mit „Org Admins“. + +--- + +## 🔧 Muss ich das `owners`-Team konfigurieren? + +### Nein – aber: + +* Du **musst es nicht konfigurieren**, es funktioniert immer. +* Du **kannst Mitglieder hinzufügen oder entfernen**, aber **nicht das Team selbst löschen oder umbenennen**. + +### ✅ Empfehlungen: + +* Nur vertrauenswürdige Personen (z. B. Projekt-Admins) sollten im `owners`-Team sein. +* Für andere Rollen (Contributor, Maintainer, Leser) solltest du **eigene Teams** mit passenden Rechten erstellen. + +--- + +## 📘 Beispiel: Organisation mit klarer Rollentrennung + +| Team | Beschreibung | Rechte | +| -------------- | ------------------------- | -------------------------- | +| `owners` | Orga-Admins (hartkodiert) | Admin | +| `maintainers` | Aktive Maintainer | Admin/Write je nach Bedarf | +| `contributors` | Beitragende Entwickler | Write | +| `readers` | Dürfen nur lesen | Read | + +--- + +Wenn du möchtest, kann ich dir auch ein Skript bauen, das sicherstellt: + +* Nur bestimmte Benutzer im `owners`-Team sind +* Alle anderen automatisch in passende andere Teams sortiert werden + +Möchtest du so ein Beispiel oder ein Review-Skript für Orga-Mitglieder und deren Rechte? diff --git a/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-2.puml b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-2.puml new file mode 100644 index 0000000..1a082ad --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-2.puml @@ -0,0 +1,57 @@ +@startuml +package "Forgejo/Gitea User-Organisation-Repo-Modell" { + + class User { + + id: int + + username: string + + email: string + } + + class Organisation { + + id: int + + name: string + } + + class OrgMember { + + user_id: int + + org_id: int + + is_owner: bool + + role: string + } + + class Team { + + id: int + + org_id: int + + name: string + + permission_level: string + } + + class Repository { + + id: int + + owner_id: int + + name: string + + is_private: bool + } + + User "1" -- "0..*" OrgMember : membership + Organisation "1" -- "0..*" OrgMember : members + Organisation "1" -- "0..*" Team : teams + Team "1" -- "0..*" User : members + Team "1" -- "0..*" Repository : repos + + Organisation "1" -- "0..*" Repository : owns + + note right of OrgMember + Owner (is_owner = true) kann: + - Organisation verwalten + - Teams erstellen/löschen + - Mitglieder verwalten + end note + + note left of Repository + Zugriff durch Teams nur möglich, wenn + Repository zu Organisation gehört. + Owner können Repository voll verwalten. + end note +} +@enduml diff --git a/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-3.puml b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-3.puml new file mode 100644 index 0000000..f1decc6 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large-3.puml @@ -0,0 +1,63 @@ +@startuml +package "Forgejo/Gitea System" { + + package "Systemweite Benutzer & Rollen" { + class User { + + id: int + + username: string + + email: string + } + } + + package Organisation { + class Organisation { + + id: int + + name: string + } + + class OrgMember { + + user_id: int + + org_id: int + + is_owner: bool + + role: string + } + + class Team { + + id: int + + org_id: int + + name: string + + permission_level: string + } + } + + package Repository { + class Repository { + + id: int + + owner_id: int + + name: string + + is_private: bool + } + } + + User "1" -- "0..*" OrgMember : membership + Organisation "1" -- "0..*" OrgMember : members + Organisation "1" -- "0..*" Team : teams + Team "1" -- "0..*" User : members + Team "1" -- "0..*" Repository : repos + + Organisation "1" -- "0..*" Repository : owns + + note right of OrgMember + Owner (is_owner = true) kann: + - Organisation verwalten + - Teams erstellen/löschen + - Mitglieder verwalten + end note + + note left of Repository + Zugriff durch Teams nur möglich, wenn + Repository zu Organisation gehört. + Owner können Repository voll verwalten. + end note +} +@enduml diff --git a/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large.puml b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large.puml new file mode 100644 index 0000000..72a41f4 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-large.puml @@ -0,0 +1,62 @@ +@startuml +left to right direction +skinparam linetype ortho +skinparam classAttributeIconSize 0 +hide circle + +' Gruppierungen +package "Systemweite Benutzer und Rollen" { + class User { + +username + +email + +isAdmin + } + + note right of User + Kann Organisationen erstellen + Kann eigenen Namespace verwalten + Kann systemweiter Admin sein + end note +} + +package "Organisation" { + class Organisation { + +name + +visibility + } + + class Team { + +name + +permissionLevel + +canCreateRepos + } + + class OrgMember { + +role: member / owner + } + + Organisation "1" -- "0..*" Team : verwaltet > + Organisation "1" -- "0..*" OrgMember : hat Mitglieder > + User "1" -- "0..*" OrgMember : ist > + + OrgMember "1" -- "0..*" Team : gehört zu > +} + +package "Repository" { + class Repository { + +name + +visibility + +owner: User|Organisation + } + + Team "1" -- "0..*" Repository : Zugriff auf > + User "1" -- "0..*" Repository : direkte Rechte (optional) > + + note right of Repository + Teams können nur auf Repositories zugreifen, + die zur selben Organisation gehören. + Nutzer-Repos können nicht über Teams geteilt werden. + end note +} + +@enduml diff --git a/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-small copy.puml b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-small copy.puml new file mode 100644 index 0000000..cb63a29 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/repo-access-model-and-organisations/user-orgamnisation-team-entity-model-small copy.puml @@ -0,0 +1,56 @@ +@startuml +left to right direction +skinparam linetype ortho +skinparam classAttributeIconSize 0 +hide circle + +' Gruppierungen +package "Systemweite Benutzer und Rollen" { + class User { + +username + +email + +isAdmin + } + + note right of User + Kann Organisationen erstellen + Kann eigenen Namespace verwalten + Kann systemweiter Admin sein + end note +} + +package "Organisation" { + class Organisation { + +name + +visibility + } + + class Team { + +name + +permissionLevel + +canCreateRepos + } + + class OrgMember { + +role: member / owner + } + + Organisation "1" -- "0..*" Team : verwaltet > + Organisation "1" -- "0..*" OrgMember : hat Mitglieder > + User "1" -- "0..*" OrgMember : ist > + + OrgMember "1" -- "0..*" Team : gehört zu > +} + +package "Repository" { + class Repository { + +name + +visibility + +owner: User|Organisation + } + + Team "1" -- "0..*" Repository : Zugriff auf > + User "1" -- "0..*" Repository : direkte Rechte (optional) > +} + +@enduml diff --git a/docs/technical-documentation/product/components/forgejo/user-onboarding/user-onbording-flow.puml b/docs/technical-documentation/product/components/forgejo/user-onboarding/user-onbording-flow.puml new file mode 100644 index 0000000..f756805 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/user-onboarding/user-onbording-flow.puml @@ -0,0 +1,31 @@ +@startuml +skinparam defaultTextAlignment center +skinparam linetype ortho + +start + +:Neuer Nutzer registriert +oder eingeladen; + +:Login am Forgejo-Server; + +partition "Eigenes Nutzerkonto" { + :Optional: SSH-Key, Avatar, Bio; + :Optional: Eigenes Repo erstellen; +} + +partition "Organisationen" { + :Neue Organisation erstellen; + :Team 'Owners' automatisch vorhanden; + :Weitere Teams erstellen; + :Bestehende Nutzer zu Teams hinzufügen; +} + +partition "Repositories" { + :Repo in Organisation erstellen; + :Teams Berechtigungen auf Repos geben; + :Optional: Webhooks, Labels, Milestones; +} + +stop +@enduml