Merge commit 'cfaf67010017eab368216aded483a64126dbcb2e' as 'bahn/wissensdatenbank'
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
# SETUP – Was du (manuell) tun musst
|
||||
|
||||
Code/Config sind vorbereitet. Diese Schritte brauchen Zugaenge/Rechte, die nur du hast.
|
||||
|
||||
## Warum kein Deps-Image? (PyPI ueber Artifactory-Mirror)
|
||||
|
||||
Die GitLab-Runner-Pods erreichen **pypi.org nicht**, **aber** den Artifactory-PyPI-Mirror
|
||||
auf bahnhub. Deshalb setzt die CI `PIP_INDEX_URL` auf den Mirror – dann funktioniert
|
||||
`pip install` direkt im Job, **ohne eigenes Image**:
|
||||
|
||||
```
|
||||
PIP_INDEX_URL = https://bahnhub.tech.rz.db.de/artifactory/api/pypi/pypi-remote/simple
|
||||
```
|
||||
|
||||
Ist bereits in `.gitlab-ci.yml` gesetzt. Falls der Repo-Name im Konzern abweicht,
|
||||
dort anpassen (beim DXP-/pipeship-Team erfragen). `lint`/`pages` brauchen kein pip.
|
||||
|
||||
---
|
||||
|
||||
## Checkliste
|
||||
|
||||
### 1. PyPI-Mirror pruefen
|
||||
- [ ] Ersten Pipeline-Lauf ansehen: `test`-Job muss `pip install` ueber den Mirror
|
||||
schaffen. Falls 403/404: `PIP_INDEX_URL` (Repo-Name) in `.gitlab-ci.yml` anpassen.
|
||||
|
||||
### 2. CI/CD-Variablen anlegen (Settings → CI/CD → Variables, Masked & Protected)
|
||||
- [ x] `CONFLUENCE_URL` = `https://arija-confluence.jaas.service.deutschebahn.com`
|
||||
- [x ] `CONFLUENCE_TOKEN` = dein Confluence-PAT (**neuen** erzeugen, alten rotieren!)
|
||||
- [x ] `GIT_PUSH_TOKEN` = Project Access Token mit Scope `write_repository`
|
||||
- [ ] (optional) `GITLAB_TOKEN` = Read-Token, falls `gitlab_md`-Quellen aus PRIVATEN
|
||||
GitLab-Repos geladen werden (oeffentliche brauchen keinen Token)
|
||||
- (DEPS_IMAGE entfaellt – pip laeuft ueber PIP_INDEX_URL, siehe oben)
|
||||
|
||||
### 3. Schedule (CI/CD → Schedules)
|
||||
- [x] Schedule angelegt: **Cron `0 8-17 * * 1-5`** (stuendlich Mo–Fr 8–17 Uhr), Target
|
||||
Branch `main`. Der `knowledge-etl`-Job laeuft nur bei `schedule`/`web`.
|
||||
|
||||
### 3b. Netzzugang des Runners (WICHTIG fuer den ETL-Lauf)
|
||||
Der Runner muss die Quellen erreichen, sonst kommen 0 Dokumente (Timeouts):
|
||||
- intern: `arija-confluence...deutschebahn.com` (Confluence)
|
||||
- oeffentlich: `www.dbinfrago.com` (Kundeninfos, INB, Regelwerk)
|
||||
|
||||
Der `knowledge-etl`-Job ist bereits auf den **DB-Web-Proxy** konfiguriert
|
||||
(`http://webproxy.comp.db.de:8080`) mit `NO_PROXY` fuer interne Hosts
|
||||
(`.tech.rz.db.de`, `.deutschebahn.com`).
|
||||
- [ ] Pruefen, ob Proxy-Host/Port stimmen (ggf. in `.gitlab-ci.yml` anpassen) und ob
|
||||
der Proxy **keine Authentifizierung** verlangt. Beim naechsten Lauf im Log sehen:
|
||||
laufen Confluence + dbinfrago jetzt durch?
|
||||
|
||||
### 4. Protected Branch + Freigabe (Settings → Repository → Protected Branches)
|
||||
- [x ] `main` schuetzen: „Allowed to push" = niemand (nur via MR); „Allowed to merge" = Maintainer.
|
||||
- [ ] Settings → Merge requests: „Require approval from Code Owners" aktivieren.
|
||||
das ignroerien wir erst mal
|
||||
- [ ] In `CODEOWNERS` die Platzhalter durch echte GitLab-Gruppen/Handles ersetzen
|
||||
(`@einfachbahn-lab/wissensdatenbank-maintainer` -> reale Gruppe).
|
||||
> das auch
|
||||
- [ ] Hinweis: Der automatische Bot-Push auf `main` braucht dann eine Ausnahme
|
||||
(Token-User als „Allowed to push" zulassen) ODER der Bot pusht auf einen Branch
|
||||
`knowledge-data` (in `.gitlab-ci.yml` `TARGET_BRANCH` umstellen) + Auto-MR.
|
||||
-> braucht es das dann noch?
|
||||
ANTWORT: Ja. Da `main` „push = niemand" ist, wuerde der automatische ETL-Push scheitern.
|
||||
Einfachste Loesung: den `GIT_PUSH_TOKEN`-User unter „Allowed to push" fuer `main`
|
||||
zulassen. (CODEOWNERS-Approval ignorieren wir ja erst mal, also kein MR-Zwang.)
|
||||
|
||||
### 5. GitLab Pages aktivieren (Deploy → Pages)
|
||||
- [ x] Nach erstem erfolgreichen `pages`-Job ist die URL unter Deploy → Pages sichtbar.
|
||||
(Job laeuft auf `main`; nutzt nur stdlib, kein Deps-Image noetig.)
|
||||
|
||||
|
||||
das hier verstehe ich noch nicht:
|
||||
### 6. Issue → MR Automatisierung (optional, fuer Self-Service)
|
||||
|
||||
Ziel: Ein Fachbereich meldet neues Wissen per **GitLab-Issue** (Vorlage „Neues Wissen"),
|
||||
ohne yaml/Git zu koennen. Daraus wird automatisch ein Eintrag in `config/tools.yaml`
|
||||
+ ein Merge Request mit Vorschau. So laeuft es:
|
||||
|
||||
1. Person legt ein **Issue** mit der Vorlage an (Tool, Link(s), Scope, Ansprechpartner)
|
||||
und Label `neues-wissen`.
|
||||
2. Aus dem Issue wird ein **tools.yaml-Eintrag** erzeugt (`scripts/issue_to_source.py`)
|
||||
und ein **MR** geoeffnet (`scripts/issue_to_mr.sh <ISSUE_ID>`), inkl. Markdown-Vorschau.
|
||||
3. Reviewer schaut die Vorschau an und merged = Freigabe.
|
||||
|
||||
Du musst nur entscheiden, WIE Schritt 2 ausgeloest wird:
|
||||
- **Manuell (einfachste Variante):** Reviewer fuehrt `scripts/issue_to_mr.sh <ISSUE_ID>`
|
||||
lokal aus (braucht `glab` eingeloggt + aktive venv + `CONFLUENCE_*`). Fuer den Anfang reicht das.
|
||||
- **Automatisch (spaeter):** GitLab-Webhook auf „Issues events" an einen kleinen Dienst,
|
||||
der das Skript ausfuehrt – ODER ein scheduled CI-Job, der offene `neues-wissen`-Issues abarbeitet.
|
||||
|
||||
- [ ] Label `neues-wissen` anlegen (fuer beide Varianten).
|
||||
- [ ] Fuer den Start: Variante „manuell" nutzen. Automatik ist optional/spaeter.
|
||||
|
||||
### 8. Reviews
|
||||
- [ passt erst mal] GitLab Pages (Uebersicht) pruefen.
|
||||
- [passt erst mal ] `pending` freigeben: URL oder `hash:<content_hash>` in
|
||||
`config/approvals.yaml` unter `approved:` eintragen.
|
||||
|
||||
---
|
||||
|
||||
## ETL-Bot - was genau noch zu tun ist
|
||||
|
||||
Der `knowledge-etl`-Job laeuft per Schedule (stuendlich Mo–Fr 8–17 Uhr), baut das Wissen und **pusht das Ergebnis
|
||||
zurueck**. Dafuer:
|
||||
|
||||
1. **`GIT_PUSH_TOKEN`** anlegen: Settings → Access Tokens → *Project Access Token*,
|
||||
Rolle `Maintainer`, Scope **`write_repository`**. Wert als CI/CD-Variable
|
||||
`GIT_PUSH_TOKEN` (Masked & Protected) speichern.
|
||||
2. **Push auf `main` erlauben** (weil `main` „push = niemand" ist): Settings →
|
||||
Repository → Protected Branches → `main` → unter **„Allowed to push"** den
|
||||
Token-User hinzufuegen (heisst typ. `project_<id>_bot`).
|
||||
- **Alternative (main bleibt strikt):** in `.gitlab-ci.yml` `TARGET_BRANCH: knowledge-data`
|
||||
setzen; der Bot pusht dann auf einen Datenbranch (kein Push auf main noetig).
|
||||
3. **Schedule** angelegt (CI/CD → Schedules, Cron `0 8-17 * * 1-5`, Target `main`). ✔
|
||||
|
||||
Mehr ist fuer den Bot nicht noetig – `pip` laeuft ueber den PyPI-Mirror.
|
||||
|
||||
## Quellen-Typen: GitLab / Datei im Repo / public
|
||||
|
||||
- **GitLab** (`gitlab_md`): ✅ Markdown-Dateien aus einem Repo, mit Ordner (`path`) und
|
||||
Tiefe (`max_depth`). Privat-Repos brauchen `GITLAB_TOKEN`.
|
||||
- **Datei im Repo** (`file`): ✅ Handbuch/Doku einfach nach `files/<tool>/` pushen und
|
||||
per `strategy: file` einbinden (PDF wird zu Text, .md direkt). Alles versioniert.
|
||||
- **PDF-Handbuecher via Link** (`pdf`): ✅ direkter PDF-Link oder Seite mit PDF-Links.
|
||||
- **Public Links** (`crawler`/`pdf`/`sitemap`): ✅.
|
||||
Reference in New Issue
Block a user