mirror of
http://172.20.10.11:3000/gitadmin/INSIGHT-MVP.git
synced 2026-06-25 00:16:41 +02:00
docs: add Forgejo CI/CD setup guide for Git server configuration
Step-by-step instructions for: - Enabling Forgejo Actions and Container Registry - Installing and registering a Forgejo Runner - Configuring repository secrets for deployment - Setting up branch protection rules - Testing the Container Registry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Thomas Reitz
parent
0e052b001c
commit
b3516c5fdd
1 changed files with 274 additions and 0 deletions
274
docs/FORGEJO_SETUP.md
Normal file
274
docs/FORGEJO_SETUP.md
Normal file
|
|
@ -0,0 +1,274 @@
|
||||||
|
# Forgejo Setup - Anleitung fuer den Git-Server
|
||||||
|
|
||||||
|
> **Ziel:** Forgejo so konfigurieren, dass CI/CD Pipelines (Forgejo Actions)
|
||||||
|
> automatisch laufen und Docker Images in die integrierte Container Registry
|
||||||
|
> gepusht werden.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Voraussetzungen pruefen
|
||||||
|
|
||||||
|
### 1.1 Forgejo Actions aktiviert?
|
||||||
|
|
||||||
|
Forgejo Actions ist seit Forgejo 1.21+ verfuegbar, muss aber in der
|
||||||
|
Server-Konfiguration aktiviert sein.
|
||||||
|
|
||||||
|
In der Forgejo-Konfiguration (`app.ini` auf dem Git-Server) pruefen:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# /etc/forgejo/app.ini (oder wo Forgejo installiert ist)
|
||||||
|
|
||||||
|
[actions]
|
||||||
|
ENABLED = true
|
||||||
|
DEFAULT_ACTIONS_URL = https://code.forgejo.org
|
||||||
|
```
|
||||||
|
|
||||||
|
Falls nicht vorhanden: Eintrag hinzufuegen und Forgejo neustarten.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo systemctl restart forgejo
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2 Container Registry aktiviert?
|
||||||
|
|
||||||
|
Die Registry muss ebenfalls in `app.ini` aktiviert sein:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[packages]
|
||||||
|
ENABLED = true
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Forgejo Actions Runner einrichten
|
||||||
|
|
||||||
|
Forgejo Actions braucht einen **Runner** (vergleichbar mit GitHub Actions
|
||||||
|
Self-Hosted Runner). Der Runner fuehrt die CI/CD-Jobs aus.
|
||||||
|
|
||||||
|
### 2.1 Runner auf dem Git-Server installieren
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Runner-Binary herunterladen (aktuelle Version pruefen auf:
|
||||||
|
# https://code.forgejo.org/forgejo/runner/releases)
|
||||||
|
|
||||||
|
# Beispiel fuer Linux x86_64:
|
||||||
|
wget https://code.forgejo.org/forgejo/runner/releases/download/v4.0.0/forgejo-runner-4.0.0-linux-amd64
|
||||||
|
chmod +x forgejo-runner-4.0.0-linux-amd64
|
||||||
|
sudo mv forgejo-runner-4.0.0-linux-amd64 /usr/local/bin/forgejo-runner
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 Runner registrieren
|
||||||
|
|
||||||
|
Zuerst ein **Registration Token** in Forgejo generieren:
|
||||||
|
|
||||||
|
1. Forgejo Web-UI oeffnen: `https://git.xinion.lan`
|
||||||
|
2. **Site Administration** > **Runners** (oben rechts Zahnrad-Icon)
|
||||||
|
3. Oder: **Repository** > **Settings** > **Actions** > **Runners**
|
||||||
|
4. Klick auf **"Create new Runner"** oder **"Registration Token"**
|
||||||
|
5. Token kopieren
|
||||||
|
|
||||||
|
Dann auf dem Server den Runner registrieren:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Runner registrieren (interaktiv)
|
||||||
|
forgejo-runner register \
|
||||||
|
--instance https://git.xinion.lan \
|
||||||
|
--token <DEIN-REGISTRATION-TOKEN> \
|
||||||
|
--name insight-runner \
|
||||||
|
--labels ubuntu-latest:docker://node:20
|
||||||
|
|
||||||
|
# Alternativ: non-interaktiv
|
||||||
|
forgejo-runner register --no-interactive \
|
||||||
|
--instance https://git.xinion.lan \
|
||||||
|
--token <DEIN-REGISTRATION-TOKEN> \
|
||||||
|
--name insight-runner \
|
||||||
|
--labels "ubuntu-latest:docker://node:20,docker:docker://docker:latest"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 Runner als Systemd-Service einrichten
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Service-Datei erstellen
|
||||||
|
sudo tee /etc/systemd/system/forgejo-runner.service > /dev/null << 'UNIT'
|
||||||
|
[Unit]
|
||||||
|
Description=Forgejo Actions Runner
|
||||||
|
After=docker.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
User=forgejo-runner
|
||||||
|
WorkingDirectory=/opt/forgejo-runner
|
||||||
|
ExecStart=/usr/local/bin/forgejo-runner daemon
|
||||||
|
Restart=always
|
||||||
|
RestartSec=10
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
UNIT
|
||||||
|
|
||||||
|
# User und Verzeichnis anlegen
|
||||||
|
sudo useradd -r -s /bin/false forgejo-runner
|
||||||
|
sudo mkdir -p /opt/forgejo-runner
|
||||||
|
sudo chown forgejo-runner:forgejo-runner /opt/forgejo-runner
|
||||||
|
|
||||||
|
# Docker-Zugriff fuer den Runner
|
||||||
|
sudo usermod -aG docker forgejo-runner
|
||||||
|
|
||||||
|
# Service starten
|
||||||
|
sudo systemctl daemon-reload
|
||||||
|
sudo systemctl enable forgejo-runner
|
||||||
|
sudo systemctl start forgejo-runner
|
||||||
|
|
||||||
|
# Status pruefen
|
||||||
|
sudo systemctl status forgejo-runner
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.4 Pruefen ob Runner aktiv ist
|
||||||
|
|
||||||
|
In Forgejo Web-UI:
|
||||||
|
- **Site Administration** > **Runners**
|
||||||
|
- Der Runner `insight-runner` sollte mit Status **"Online"** erscheinen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Repository-Einstellungen
|
||||||
|
|
||||||
|
### 3.1 Actions fuer das Repository aktivieren
|
||||||
|
|
||||||
|
1. Repository oeffnen: `https://git.xinion.lan/gitadmin/INSIGHT-MVP`
|
||||||
|
2. **Settings** > **Repository**
|
||||||
|
3. Unter **"Actions"**: Haken setzen bei **"Enable Repository Actions"**
|
||||||
|
4. Speichern
|
||||||
|
|
||||||
|
### 3.2 Repository Secrets anlegen
|
||||||
|
|
||||||
|
Die CI/CD-Pipeline braucht Secrets fuer den Server-Zugang.
|
||||||
|
|
||||||
|
1. **Settings** > **Actions** > **Secrets**
|
||||||
|
2. Folgende Secrets anlegen:
|
||||||
|
|
||||||
|
| Secret Name | Wert | Zweck |
|
||||||
|
|---------------------|---------------------------------------------------------|-----------------------------|
|
||||||
|
| `SSH_DEPLOY_KEY` | Inhalt von `.keys/cicd_ed25519` (Private Key) | SSH-Zugriff auf Server |
|
||||||
|
| `DEPLOY_HOST` | IP-Adresse von `insight-dev-01` | Server-Adresse |
|
||||||
|
| `DEPLOY_USER` | `deploy` | SSH-User auf dem Server |
|
||||||
|
| `REGISTRY_USER` | Forgejo-Username (z.B. `gitadmin`) | Container Registry Login |
|
||||||
|
| `REGISTRY_PASSWORD` | Forgejo-Passwort oder Access Token | Container Registry Login |
|
||||||
|
|
||||||
|
#### SSH Key als Secret hinterlegen
|
||||||
|
|
||||||
|
Den **kompletten** Inhalt des Private Keys kopieren:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Auf dem MacBook ausfuehren:
|
||||||
|
cat .keys/cicd_ed25519
|
||||||
|
```
|
||||||
|
|
||||||
|
Den gesamten Output (inkl. `-----BEGIN OPENSSH PRIVATE KEY-----` und
|
||||||
|
`-----END OPENSSH PRIVATE KEY-----`) in das Secret-Feld einfuegen.
|
||||||
|
|
||||||
|
#### Forgejo Access Token erstellen (fuer Registry)
|
||||||
|
|
||||||
|
Statt Passwort empfehlen wir einen **Access Token**:
|
||||||
|
|
||||||
|
1. Forgejo Web-UI > **Profil** (oben rechts) > **Settings** > **Applications**
|
||||||
|
2. **Generate New Token**
|
||||||
|
3. Name: `insight-registry`
|
||||||
|
4. Berechtigungen: `write:package` (oder `package` Scope)
|
||||||
|
5. Token kopieren und als `REGISTRY_PASSWORD` Secret anlegen
|
||||||
|
|
||||||
|
### 3.3 Branch Protection einrichten
|
||||||
|
|
||||||
|
1. **Settings** > **Branches**
|
||||||
|
2. **Add Branch Protection Rule**
|
||||||
|
|
||||||
|
Fuer `main`:
|
||||||
|
- **Branch name pattern:** `main`
|
||||||
|
- **Enable push:** Deaktiviert (nur via Merge)
|
||||||
|
- **Required approvals:** 1
|
||||||
|
- **Status checks must pass:** Aktiviert
|
||||||
|
|
||||||
|
Fuer `develop`:
|
||||||
|
- **Branch name pattern:** `develop`
|
||||||
|
- **Enable push:** Deaktiviert (nur via Merge)
|
||||||
|
- **Required approvals:** 1
|
||||||
|
- **Status checks must pass:** Aktiviert
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Container Registry testen
|
||||||
|
|
||||||
|
### 4.1 Vom MacBook aus testen
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In die Forgejo Registry einloggen
|
||||||
|
docker login git.xinion.lan -u <FORGEJO-USERNAME>
|
||||||
|
# Passwort oder Access Token eingeben
|
||||||
|
|
||||||
|
# Test-Image taggen und pushen
|
||||||
|
docker pull hello-world
|
||||||
|
docker tag hello-world git.xinion.lan/gitadmin/insight-test:latest
|
||||||
|
docker push git.xinion.lan/gitadmin/insight-test:latest
|
||||||
|
|
||||||
|
# Aufraumen
|
||||||
|
docker rmi git.xinion.lan/gitadmin/insight-test:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 In Forgejo pruefen
|
||||||
|
|
||||||
|
1. Repository > **Packages** Tab
|
||||||
|
2. Das `insight-test` Image sollte sichtbar sein
|
||||||
|
3. Nach dem Test kann es geloescht werden
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Checkliste
|
||||||
|
|
||||||
|
Bitte alle Punkte abarbeiten und abhaken:
|
||||||
|
|
||||||
|
- [ ] `app.ini`: `[actions] ENABLED = true` gesetzt
|
||||||
|
- [ ] `app.ini`: `[packages] ENABLED = true` gesetzt
|
||||||
|
- [ ] Forgejo neugestartet nach Config-Aenderung
|
||||||
|
- [ ] Forgejo Runner installiert und registriert
|
||||||
|
- [ ] Runner laeuft als Systemd-Service und ist "Online"
|
||||||
|
- [ ] Repository Actions aktiviert (Settings > Repository)
|
||||||
|
- [ ] Secret `SSH_DEPLOY_KEY` angelegt (CI/CD Private Key)
|
||||||
|
- [ ] Secret `DEPLOY_HOST` angelegt (Server-IP)
|
||||||
|
- [ ] Secret `DEPLOY_USER` angelegt (`deploy`)
|
||||||
|
- [ ] Secret `REGISTRY_USER` angelegt (Forgejo Username)
|
||||||
|
- [ ] Secret `REGISTRY_PASSWORD` angelegt (Access Token)
|
||||||
|
- [ ] Branch Protection fuer `main` eingerichtet
|
||||||
|
- [ ] Branch Protection fuer `develop` eingerichtet
|
||||||
|
- [ ] Container Registry getestet (docker push/pull funktioniert)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Haeufige Probleme
|
||||||
|
|
||||||
|
### Runner startet nicht
|
||||||
|
```bash
|
||||||
|
# Logs pruefen
|
||||||
|
sudo journalctl -u forgejo-runner -f
|
||||||
|
|
||||||
|
# Hat der Runner Docker-Zugriff?
|
||||||
|
sudo -u forgejo-runner docker ps
|
||||||
|
```
|
||||||
|
|
||||||
|
### Actions werden nicht getriggert
|
||||||
|
- Ist Actions im Repository aktiviert? (Settings > Repository)
|
||||||
|
- Liegt die Workflow-Datei unter `.forgejo/workflows/`?
|
||||||
|
- Ist der Runner online? (Site Administration > Runners)
|
||||||
|
|
||||||
|
### Registry Push schlaegt fehl
|
||||||
|
```bash
|
||||||
|
# Login testen
|
||||||
|
docker login git.xinion.lan
|
||||||
|
|
||||||
|
# Ist die Registry aktiviert?
|
||||||
|
# In app.ini: [packages] ENABLED = true
|
||||||
|
```
|
||||||
|
|
||||||
|
### Branch Protection blockiert Push
|
||||||
|
- Korrekt! Main und Develop sind geschuetzt.
|
||||||
|
- Feature-Branches erstellen: `git checkout -b feature/mein-feature`
|
||||||
|
- Push auf Feature-Branch, dann Pull Request erstellen
|
||||||
Loading…
Add table
Reference in a new issue