mirror of
http://172.20.10.11:3000/gitadmin/INSIGHT-MVP.git
synced 2026-06-24 22:46:39 +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