Git-Integration

Polycrate bietet eine native Git-Integration basierend auf go-git, die ohne externe Git-Installation funktioniert. Alle Git-Operationen werden direkt in der CLI ausgeführt.

Überblick

graph LR
    User[Entwickler] --> Status[polycrate git status]
    User --> Add[polycrate git add]
    User --> Commit[polycrate git commit]
    User --> Push[polycrate git push]
    User --> Pull[polycrate git pull]
    User --> Sync[polycrate git sync]

    Sync --> |1. Stage| Add
    Sync --> |2. Commit| Commit
    Sync --> |3. Pull| Pull
    Sync --> |4. Push| Push

Einen bestehenden API-Workspace lokal holen: `polycrate workspace clone ORG/WORKSPACE` (go-git, `git_ssh_url` aus der API). Das ist kein `polycrate git`-Subcommand. → [Workspace klonen](workspaces.md#workspace-klonen-api)

Verfügbare Commands

`polycrate git status`

Zeigt den Status des Workspace-Repositories an.

polycrate git status

Ausgabe:

Branch: main
Commit: a1b2c3d (feat: add new feature)

Staged changes:
  new:      blocks/my-block/block.poly
  modified: workspace.poly

Unstaged changes:
  modified: artifacts/config.yml

Untracked files:
  temp.txt

Farbcodierung:

Status	Farbe	Bedeutung
`new:`	Grün	Neue Datei
`modified:`	Gelb	Geänderte Datei
`deleted:`	Rot	Gelöschte Datei
`renamed:`	Cyan	Umbenannte Datei
`copied:`	Cyan	Kopierte Datei

`polycrate git add`

Stagt Dateien für den nächsten Commit.

# Einzelne Datei stagen
polycrate git add <datei>

# Alle Änderungen stagen
polycrate git add --all
polycrate git add -a

Beispiele:

polycrate git add workspace.poly
polycrate git add blocks/my-block/
polycrate git add --all

`polycrate git commit`

Erstellt einen neuen Commit mit den gestagten Änderungen.

polycrate git commit --message "Commit-Nachricht"
polycrate git commit -m "Commit-Nachricht"

Optionen:

Flag	Beschreibung
`-m, --message`	Commit-Nachricht (erforderlich)

Beispiele:

polycrate git commit -m "feat: add database block"
polycrate git commit -m "fix: correct kubeconfig path"

`polycrate git push`

Pusht lokale Commits zum Remote-Repository.

polycrate git push

Features:

Zeigt Spinner während des Push-Vorgangs
Automatische Authentifizierung via SSH-Key aus dem Workspace

`polycrate git pull`

Pullt Änderungen vom Remote-Repository.

polycrate git pull

Features:

Conflict-Erkennung VOR dem Pull: Prüft ob lokale Änderungen mit Remote-Änderungen kollidieren würden
Zeigt Spinner während des Pull-Vorgangs

Bei Konflikten:

Error: Cannot pull - local changes would be overwritten:
  - workspace.poly
  - blocks/my-block/config.yml

Please commit or stash your changes before pulling.

`polycrate git sync`

Automatischer Sync-Workflow: Commit, Pull, Push in einem Schritt.

polycrate git sync

Ablauf:

Stage: Alle Änderungen werden gestagt (git add --all)
Commit: Automatischer Commit mit generierter Nachricht
Pull: Remote-Änderungen werden geholt
Push: Lokale Commits werden gepusht

Beispiel:

$ polycrate git sync

Staging all changes...
  ✓ 3 files staged

Creating commit...
  ✓ Commit created: "polycrate: sync workspace"

Pulling from remote...
  ✓ Already up to date

Pushing to remote...
  ✓ Pushed to origin/main

Sync completed successfully.

Anwendungsfall:

Ideal für schnelle Synchronisierung nach Änderungen:

# Nach dem Ausführen einer Action
polycrate run my-block deploy

# Workspace synchronisieren
polycrate git sync

Workflow-Beispiele

Täglicher Workflow

# 1. Morgens: Remote-Änderungen holen
polycrate git pull

# 2. Arbeiten...
polycrate run my-block configure

# 3. Status prüfen
polycrate git status

# 4. Änderungen committen
polycrate git add --all
polycrate git commit -m "feat: update configuration"

# 5. Pushen
polycrate git push

Schneller Sync

# Alles in einem Schritt
polycrate git sync

Selektives Committen

# Nur bestimmte Dateien committen
polycrate git add workspace.poly
polycrate git add blocks/important-block/
polycrate git commit -m "feat: update important block"
polycrate git push

# Andere Änderungen später
polycrate git add --all
polycrate git commit -m "chore: minor updates"
polycrate git push

Integration mit Workspace List

Die Workspace List zeigt Git-Informationen für jeden Workspace:

polycrate workspace list

NAME                 ORG         ENC   MODIFIED         COMMIT     STATUS   AUTHOR
production           acme        🔒    2024-01-15 10:30 a1b2c3d    clean    John Doe
staging              acme              2024-01-14 16:45 d4e5f6g    dirty    Jane Smith

COMMIT: Short-Hash des letzten Commits
STATUS: clean (keine Änderungen) oder dirty (uncommitted changes)
AUTHOR: Autor des letzten Commits

Auto-Commit (optional)

Polycrate kann automatisch nach jeder Action committen:

polycrate run my-block deploy --auto-commit

Oder in der workspace.poly:

config:
  auto_commit: true

Dies erstellt automatisch einen Commit mit Transaction-ID nach jeder erfolgreichen Action.

SSH-Authentifizierung

Git-Operationen nutzen den dateibasierten SSH-Key aus dem Workspace (go-git, ab CLI 0.45.0 ohne Host-SSH_AUTH_SOCK-Strategie — vermeidet Fehler, wenn z. B. der GPG-Agent als SSH-Agent läuft):

Neuer Pfad: artifacts/secrets/id_rsa
Legacy-Pfad: id_rsa im Workspace-Root

Bei Passphrase-geschützten Keys erscheint ein interaktiver Prompt. Bei verschlüsselten Workspaces muss der Workspace vor Git-Operationen entschlüsselt sein:

polycrate workspace decrypt
polycrate git pull

SSH-Key mit Passphrase

polycrate --ssh-use-passphrase git push

Siehe SSH-Dokumentation für Details zu Action-Runs und Agent-Mount.

Unterschied zu externem Git

Aspekt	`polycrate git`	`git` (extern)
Installation	Keine nötig (eingebaut)	Erfordert Git-Installation
SSH-Key	Nutzt Workspace-Key automatisch	Erfordert Konfiguration
Conflict-Check	Vor dem Pull	Nach dem Pull (Merge-Konflikt)
Spinner	Ja	Nein
Farbige Ausgabe	Optimiert für Polycrate	Standard-Git-Farben

Best Practices

1. Vor Actions synchronisieren

polycrate git pull
polycrate run my-block deploy
polycrate git sync

2. Aussagekräftige Commit-Messages

# Conventional Commits verwenden
polycrate git commit -m "feat: add redis caching"
polycrate git commit -m "fix: correct database connection string"
polycrate git commit -m "chore: update dependencies"

3. Regelmäßig pushen

Verlorene Arbeit vermeiden durch regelmäßiges Pushen:

# Nach jeder größeren Änderung
polycrate git sync

4. Status vor Commit prüfen

polycrate git status
# Prüfen was gestagt wird
polycrate git add --all
polycrate git commit -m "..."

Fehlerbehebung

"Authentication failed"

# Prüfen ob SSH-Key existiert
ls -la artifacts/secrets/id_rsa

# Oder im Root
ls -la id_rsa

# Key-Berechtigungen prüfen
chmod 600 artifacts/secrets/id_rsa

"Remote rejected"

# Erst pullen, dann pushen
polycrate git pull
polycrate git push

"Local changes would be overwritten"

# Option 1: Commit vor Pull
polycrate git add --all
polycrate git commit -m "save local changes"
polycrate git pull

# Option 2: Änderungen verwerfen (VORSICHT!)
git checkout -- .
polycrate git pull

Siehe auch

CLI-Referenz - Vollständige Command-Referenz
Workspaces - Workspace-Grundlagen
SSH - SSH-Key-Management
Integrationen - Übersicht aller Integrationen