GUIDE GitHub Actions and Continuous‐Integration

Letztes Update: 04. Februar 2026

Der Guide behandelt folgende Themen:

1. Grundlagen
2. Initialer Sync im neuen Repositorium
3. Sync zu bestehenden Repositorien
4. Persönlicher Zugangstoken für Sync erstellen
5. Wichtige Konzept kurz erklärt

Finden Sie nicht das relevante Konzept? Dann prüfen Sie die offizielle Github Actions-Dokumentation.

---

1. Grundlagen

1. Verzeichnis: Workflows sind YAML-Dateien im Verzeichnis .github/workflows/ deines Repositories.

2. Struktur einer Workflow-Datei (*.yml): Ein einfacher Workflow könnte so aussehen:

   name: Beispiel Workflow
   on: [push] # Auslöser, z.B. bei jedem Push
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Code auschecken
           uses: actions/checkout@v4
         - name: Hallo Welt ausgeben
           run: echo "Hallo Welt!"

   • name: Der Name des Workflows.
   • on: Das Ereignis (Trigger).
   • jobs: Enthält einen oder mehrere Jobs.
   • jobs.<job_id>.runs-on: Definiert den Runner (Betriebssystem).
   • jobs.<job_id>.steps: Liste von Schritten.
     • uses: Nutzt fertige Marketplace Actions.
     • run: Führt Shell-Befehle aus.

---

2. Initialer Sync im NEUEN Repository (Labels)

Nachdem ein neues Repo aus dem Template erstellt wurde, müssen die Labels einmalig manuell synchronisiert werden:

1. Gehe zum neu erstellten Repository.
2. Gehe zum Tab "Actions".
3. Wähle den Workflow "Sync Labels from Template (Script)" (oder ähnlich benannt). Dieser Workflow wurde aus dem Template mitkopiert.
4. Klicke auf "Run workflow".
5. Gib bei template_repo den Namen des Template-Repositories ein: HisQu/template-repository.
6. Klicke auf "Run workflow".
   • Dieser Workflow nutzt das Standard GITHUB_TOKEN des neuen Repos und benötigt keine spezielle Konfiguration.

---

3. Sync zu BESTEHENDEN Repositories (Labels & Issue Templates)

Um Labels und Issue Templates auf bereits existierende Repositories anzuwenden oder diese nachträglich zu aktualisieren:

1. Workflow: Nutze den Workflow Sync Settings to Existing Repos. WICHTIG: Dieser Workflow wird im Template-Repository (HisQu/template-repository) ausgeführt, nicht in den Ziel-Repos!
2. Trigger: Gehe zum Actions-Tab des Template-Repositories (HisQu/template-repository), wähle den Workflow "Sync Settings to Existing Repos" aus und klicke auf "Run workflow".
3. Inputs:
   • target_repos: Gib eine komma-separierte Liste der Ziel-Repos an (Format: HisQu/repo1,HisQu/repo2).
   • template_repo: Sollte standardmäßig HisQu/template-repository sein.
   • prune_labels: true, um Labels in Ziel-Repos zu löschen, die nicht im Template sind. Standard: false.
   • force_update_issue_templates: true, um existierende Issue Templates im Ziel-Repo zu überschreiben. Standard: false.
4. Benötigt PAT: Dieser Workflow braucht ein Personal Access Token (PAT) mit erweiterten Rechten, da er von einem Repo auf viele andere zugreift.

---

4. Personal Access Token (PAT) für Sync erstellen

Das Sync Settings to Existing Repos-Workflow benötigt ein Token mit Rechten für das Template-Repo und alle Ziel-Repos.

Empfehlung: Fine-grained PAT erstellen:

1. Ort: Persönliche GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens.
2. Details: Klicke "Generate new token", gib Name (z.B. HisQu Repo Sync Token) & Ablaufdatum (z.B. 90 Tage) an.
3. Resource owner: Wähle die Organisation HisQu aus.
4. Repository access: Wähle "Only select repositories" -> Füge Template-Repo (HisQu/template-repository) + alle relevanten Ziel-Repos hinzu. (Muss bei neuen Ziel-Repos ggf. erweitert werden!)
5. Permissions: Repository permissions -> Contents: Read & write, Issues: Read & write.
6. Generieren & Kopieren: Token generieren und sofort kopieren.
7. Genehmigung (WICHTIG): Ein HisQu Org Owner muss das Token genehmigen (Org Settings > Personal access tokens > Pending requests).
8. Als Secret speichern: Genehmigtes Token als Organization Secret (z.B. ORG_SYNC_PAT) speichern (Org Settings > Security > Secrets and variables > Actions) und dem Template-Repo Zugriff darauf geben.

Sicherheitshinweis: Erstelle Tokens immer mit den minimal nötigen Rechten. Das Token läuft ab (z.B. 90 Tage) und muss dann neu erstellt/aktualisiert werden.

---

5. Wichtige Konzepte (Kurz)

• Secrets: Sicheres Speichern von sensiblen Daten (wie PATs) über secrets.SECRET_NAME im Workflow.
• Permissions: Der permissions: Block in Workflows definiert die Rechte des Standard GITHUB_TOKEN.
• Marketplace Actions: Fertige Actions (uses: org/repo@version) für Standardaufgaben nutzen (z.B. actions/checkout, actions/github-script).