Git Connector

Git Connector

Git Connector (Express) synchronizuje Strapi eventy organizací a uživatelů do Gitea (git hosting) — vytváří repozitáře, spravuje oprávnění a synchronizuje SSH klíče.

Klíčové údaje

• Port: 3002
• Tech: Express, TypeScript, Axios
• Messaging: RabbitMQ (exchange git.events)
• Cíl: Gitea Toolbox (9023) + Gitea Apps (9034)
• Logging: Winston

Účel

Git Connector propojuje Strapi eventy a Gitea:

1. Vytvoření uživatele → vytvoří Gitea uživatele
2. Vytvoření organizace → vytvoří Gitea organizaci
3. Přidání člena → přidá uživatele do org v Gitea
4. Změna SSH klíče → aktualizuje SSH klíče v Gitea
5. Synchronizace repozitáře → mirroruje šablony z Toolbox do Apps

Architektura

Dvě Gitea instance

Instance	Port	Účel	Databáze
Toolbox	9023	Systémové repozitáře, šablony, sdílené nástroje	Sdílená MySQL (3308)
Apps	9034	Uživatelské/org repozitáře, aplikace	Sdílená MySQL (3308)
SSH	9022 (Toolbox), 9033 (Apps)	Git přes SSH	—

Poznámka

Primární instance je Gitea Apps (port 9034). Od FÁZE-1.12 jsou všechny uživatelské a organizační repozitáře spravovány výhradně přes instanci Apps. Instance Toolbox (9023) je zachována pouze pro legacy systémové repozitáře a šablony — nové integrace cílejte na Apps.

Git Connector spravuje obě instance samostatnými API voláními.

Průběh synchronizace

Strapi event (org.create)
  ↓
RabbitMQ: org.events (routing key: create)
  ↓
Git Connector konzumuje event
  ├─ Extrahuje data organizace
  ├─ Vytvoří org v Toolbox (POST /api/v1/orgs)
  ├─ Vytvoří org v Apps (POST /api/v1/orgs)
  └─ Synchronizuje členy (přidá uživatele do org v obou instancích)
  ↓
Webhook zpět do Strapi (volitelné, pro audit)
  ↓
Frontend vidí organizaci připravenou pro Git operace

Zpracování eventů

Organization eventy

Event	Akce
org.create	Vytvoří Gitea org v Toolbox + Apps
org.update	Aktualizuje název/popis Gitea org
org.delete	Smaže Gitea org (soft delete, pokud existují repozitáře)

Member eventy

Event	Akce
org.member.added	Přidá uživatele do Gitea org
org.member.removed	Odebere uživatele z Gitea org
org.member.role.changed	Aktualizuje Gitea tým (admin/member)

User eventy

Event	Akce
user.create	Vytvoří Gitea uživatele
user.update	Aktualizuje username/email
user.ssh-key.added	Přidá SSH veřejný klíč do Gitea
user.ssh-key.removed	Odebere SSH klíč z Gitea

Konfigurace

.env proměnné:

# Gitea instance
GITEA_TOOLBOX_URL=http://gitea-toolbox:3000
GITEA_TOOLBOX_ADMIN_TOKEN=<token>

GITEA_APPS_URL=http://gitea-apps:3000
GITEA_APPS_ADMIN_TOKEN=<token>

# RabbitMQ
RABBITMQ_URL=amqp://admin:admin@sencai-mq:5672

# Port
PORT=3002

# Logging
LOG_LEVEL=info

Gitea Admin Token

Vytvoření admin tokenu:

1. Připojení do Gitea kontejneru: docker exec -it gitea-toolbox bash
2. Spustit: gitea admin user change-password admin --password <newpass>
3. Přihlásit se do Gitea UI: http://localhost:9023
4. Settings → Applications → Generate new token
5. Zkopírovat token a nastavit v .env

Nebo použít Gitea CLI:

docker exec gitea-toolbox gitea admin user change-password admin --password admin
docker exec gitea-toolbox gitea admin user generate-access-token -u admin -n sencai

Provisioning

POST /org/provision vytvoří Gitea organizaci v instanci Apps a zaregistruje potřebnou týmovou strukturu. Nevytváří žádné výchozí repozitáře — žádné policies, config ani infrastructure repozitáře se nevytvoří automaticky. Vytvoření repozitáře je vždy explicitní akce uživatele přes frontend nebo přímé volání API.

HTTP API

Všechny endpointy jsou dostupné na portu 3002. Endpointy pod /org/ vyžadují hlavičku X-Service-Secret. Kompletní seznam endpointů viz git-connector/CLAUDE.md.

Infrastruktura

Metoda	Cesta	Popis
GET	/health	Health check — konektivita Gitea Toolbox + Apps
GET	/status	Stav instance a statistiky
POST	/sync	Manuální spuštění synchronizace
GET	/queue/stats	Statistiky RabbitMQ front
POST	/cleanup/duplicates	Odstranění duplicitních záznamů repozitářů ve Strapi
POST	/webhooks/repository	Gitea příchozí webhook (vyžaduje WEBHOOK_ENABLED)

Provisioning

Metoda	Cesta	Popis
POST	/org/provision	Vytvoření Gitea organizace (bez výchozích repozitářů)
DELETE	/org/:slug/teardown	Archivace organizace — všechny repozitáře přejdou do read-only
GET	/org/:slug/repos	Seznam repozitářů organizace
POST	/org/:slug/repos	Vytvoření nového repozitáře
GET	/org/:slug/packages	Seznam balíčků (container, helm, generic, npm, pypi)
GET	/org/:slug/ci	Seznam workflow runů (Gitea Actions API)
GET	/org/:slug/mirrors	Seznam mirror repozitářů
POST	/org/:slug/mirrors	Vytvoření mirror repozitáře
DELETE	/org/:slug/mirrors/:repoName	Smazání mirror repozitáře
POST	/org/:slug/tokens	Vytvoření personal access tokenu pro člena org

Repozitáře

Metoda	Cesta	Popis
GET	/org/:slug/repo/:repo	Detail repozitáře
DELETE	/org/:slug/repo/:repo	Smazání repozitáře
PUT	/org/:slug/repo/:repo	Aktualizace nastavení repozitáře (name, description, private, has_issues, website)
GET	/org/:slug/repo/:repo/branches	Seznam větví
GET	/org/:slug/repo/:repo/commits	Nedávné commity (query: limit, max 50)
GET	/org/:slug/repo/:repo/issues	Seznam issues (query: state, limit)

Webhooky

Metoda	Cesta	Popis
GET	/org/:slug/repo/:repo/webhooks	Seznam webhooků repozitáře
POST	/org/:slug/repo/:repo/webhooks	Vytvoření webhooku (body: url, secret, events, active)
DELETE	/org/:slug/repo/:repo/webhooks/:id	Smazání webhooku

Deploy Keys

Metoda	Cesta	Popis
GET	/org/:slug/repo/:repo/keys	Seznam deploy klíčů
POST	/org/:slug/repo/:repo/keys	Přidání deploy klíče (body: title, key, read_only)
DELETE	/org/:slug/repo/:repo/keys/:id	Smazání deploy klíče

Secrets & Variables (Actions)

Metoda	Cesta	Popis
GET	/org/:slug/repo/:repo/secrets	Seznam Actions secrets
PUT	/org/:slug/repo/:repo/secrets/:name	Vytvoření nebo aktualizace secretu (body: data)
DELETE	/org/:slug/repo/:repo/secrets/:name	Smazání secretu
GET	/org/:slug/repo/:repo/variables	Seznam Actions variables
PUT	/org/:slug/repo/:repo/variables/:name	Vytvoření nebo aktualizace variable (body: value)
DELETE	/org/:slug/repo/:repo/variables/:name	Smazání variable

Soubory

Metoda	Cesta	Popis
GET	/org/:slug/repo/:repo/tree	Adresářový strom (query: path, ref — výchozí HEAD)
GET	/org/:slug/repo/:repo/content	Obsah souboru jako raw text (query: path povinný, ref)

Gitea Actions

Gitea Actions je povolena přes sekci [actions] v app.ini:

[actions]
ENABLED = true
WORKFLOW_DIRS = .sencai/workflows,.gitea/workflows,.github/workflows

Adresář .sencai/workflows/ se prohledá jako první — je to doporučené umístění pro Sencai-nativní workflow soubory. Adresáře .gitea/workflows/ a .github/workflows/ jsou podporovány kvůli kompatibilitě s existujícími pipeline.

Omezení:

• Mirror repozitáře nespouštějí Actions. Při synchronizaci mirroru Gitea nevygeneruje event push, takže workflow s on: push se nespustí. Použijte místo toho on: schedule nebo on: workflow_dispatch.
• Runnery musí být zaregistrovány, než může jakýkoliv workflow proběhnout. Fronta čeká donekonečna, dokud se nepřipojí odpovídající runner.

API endpoints (legacy sekce)

Health

GET /health

Response:
{
  "status": "up",
  "gitea": {
    "toolbox": "connected",
    "apps": "connected"
  }
}

Webhook (od RabbitMQ consumeru)

POST /api/webhook (interní, přímý přístup není potřeba)

Trigger Sync

POST /api/sync/:organisationId

Response:
{
  "status": "synced",
  "organisation": "org-name",
  "toolbox": "created",
  "apps": "created"
}

Gitea API operace

Git Connector volá Gitea API (v1):

Vytvoření organizace

POST http://gitea-toolbox:3000/api/v1/orgs
Authorization: token <ADMIN_TOKEN>

{
  "username": "org-name",
  "full_name": "Organization Name",
  "description": "Org description",
  "website": "https://sencai.space",
  "location": "Remote"
}

Přidání uživatele do organizace

POST http://gitea-toolbox:3000/api/v1/orgs/org-name/teams
Authorization: token <ADMIN_TOKEN>

{
  "name": "Developers",
  "permission": "write",  # nebo "read", "admin"
  "includes_all_repositories": true
}

Vytvoření SSH klíče pro uživatele

POST http://gitea-toolbox:3000/api/v1/user/keys
Authorization: token <USER_TOKEN>

{
  "title": "My SSH Key",
  "key": "ssh-rsa AAAAB3...",
  "read_only": false
}

RabbitMQ eventy

Git Connector konzumuje z exchange git.events a org.events.

Příklad payloadu eventu:

{
  "event": "org.create",
  "organisation": {
    "id": 1,
    "name": "acme-corp",
    "description": "Acme AI Team",
    "ownerId": 10
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Logging

# Zobrazení logů
docker logs -f git-connector

# Ukázka výstupu:
2024-01-01T12:00:00Z [INFO] Received event: org.create
2024-01-01T12:00:00Z [INFO] Creating Gitea org: acme-corp in Toolbox
2024-01-01T12:00:01Z [INFO] Creating Gitea org: acme-corp in Apps
2024-01-01T12:00:02Z [INFO] Organization synced successfully

Troubleshooting

Q: „Gitea connection refused”

A: Gitea neběží nebo není dostupná:

docker logs gitea-toolbox
docker logs gitea-apps

# Ověřte, že profil git běží: ./run-local.sh git

Q: „Invalid admin token”

A: Token je expirovaný nebo nesprávný. Vygenerujte nový token v Gitea UI (Settings → Applications).

Q: Organizace se nevytvoří v Gitea

A: Zkontrolujte logy Git Connectoru kvůli chybám. Ověřte:

1. RabbitMQ běží: docker logs sencai-mq
2. Event je publikován: zkontrolujte RabbitMQ UI (localhost:15672)
3. Git Connector konzumuje: docker logs git-connector

Q: SSH klíče se nesynchronizují

A: Ověřte:

• Formát SSH klíče je platný (začíná ssh-rsa nebo ssh-ed25519)
• Uživatel existuje v Gitea
• Token uživatele má oprávnění write

Q: Chyba „User already exists”

A: Uživatel už v Gitea může existovat z předchozí synchronizace. Kontrola idempotence možná potřebuje zlepšit.

Q: Nelze pushnout do Gitea repa přes SSH

A: Ověřte:

• SSH klíč je přidán k Gitea uživateli
• SSH port (9022 pro Toolbox, 9033 pro Apps) je otevřený
• Git URL používá správný formát: git@localhost:orgname/reponame.git