Git Integration

Polycrate's native go-git based Git integration: status, add, commit, push, pull and sync commands, workspace aliases, auto-commit, SSH authentication, differences to external Git and troubleshooting.

Git Integration

Polycrate offers a native Git integration based on go-git that works without an external Git installation. All Git operations are executed directly in the CLI.

Overview

graph LR
    User[Developer] --> 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
To fetch an existing API workspace locally: `polycrate workspace clone ORG/WORKSPACE` (go-git, `git_ssh_url` from the API). This is not a `polycrate git` subcommand. → [Cloning a workspace](/docs/polycrate/workspaces/#cloning-a-workspace-api)

Available commands

polycrate git status

Shows the status of the workspace repository.

polycrate git status

Output:

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

Color coding:

Status Color Meaning
new: Green New file
modified: Yellow Modified file
deleted: Red Deleted file
renamed: Cyan Renamed file
copied: Cyan Copied file

polycrate git add

Stages files for the next commit.

# Stage a single file
polycrate git add <file>

# Stage all changes
polycrate git add --all
polycrate git add -a

Examples:

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

polycrate git commit

Creates a new commit with the staged changes.

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

Options:

Flag Description
-m, --message Commit message (required)

Examples:

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

polycrate git push

Pushes local commits to the remote repository.

polycrate git push

Features:

  • Shows a spinner during the push
  • Automatic authentication via the SSH key from the workspace

polycrate git pull

Pulls changes from the remote repository.

polycrate git pull

Features:

  • Conflict detection BEFORE the pull: checks whether local changes would collide with remote changes
  • Shows a spinner during the pull

On conflicts:

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

Automatic sync workflow: commit, pull, push in one step.

polycrate git sync

Sequence:

  1. Stage: all changes are staged (git add --all)
  2. Commit: automatic commit with a generated message
  3. Pull: remote changes are fetched
  4. Push: local commits are pushed

Example:

$ 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.

Use case:

Ideal for quick synchronization after changes:

# After running an action
polycrate run my-block deploy

# Synchronize the workspace
polycrate git sync

Workflow examples

Daily workflow

# 1. Morning: fetch remote changes
polycrate git pull

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

# 3. Check status
polycrate git status

# 4. Commit changes
polycrate git add --all
polycrate git commit -m "feat: update configuration"

# 5. Push
polycrate git push

Quick sync

# Everything in one step
polycrate git sync

Selective committing

# Commit only specific files
polycrate git add workspace.poly
polycrate git add blocks/important-block/
polycrate git commit -m "feat: update important block"
polycrate git push

# Other changes later
polycrate git add --all
polycrate git commit -m "chore: minor updates"
polycrate git push

Integration with workspace list

The workspace list shows Git information for every 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 of the last commit
  • STATUS: clean (no changes) or dirty (uncommitted changes)
  • AUTHOR: author of the last commit

Auto-commit (optional)

Polycrate can commit automatically after every action:

polycrate run my-block deploy --auto-commit

Or in workspace.poly:

config:
  auto_commit: true

This automatically creates a commit with the transaction ID after every successful action.

SSH authentication

Git operations use the file-based SSH key from the workspace (go-git, since CLI 0.45.0 without the host SSH_AUTH_SOCK strategy — avoids errors when e.g. the GPG agent runs as the SSH agent):

  1. New path: artifacts/secrets/id_rsa
  2. Legacy path: id_rsa in the workspace root

For passphrase-protected keys an interactive prompt appears. For encrypted workspaces, the workspace must be decrypted before Git operations:

polycrate workspace decrypt
polycrate git pull

SSH key with passphrase

polycrate --ssh-use-passphrase git push

See the SSH documentation for details on action runs and agent mount.

Difference to external Git

Aspect polycrate git git (external)
Installation None required (built in) Requires a Git installation
SSH key Uses the workspace key automatically Requires configuration
Conflict check Before the pull After the pull (merge conflict)
Spinner Yes No
Colored output Optimized for Polycrate Standard Git colors

Best practices

1. Synchronize before actions

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

2. Meaningful commit messages

# Use Conventional Commits
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. Push regularly

Avoid lost work by pushing regularly:

# After every major change
polycrate git sync

4. Check status before committing

polycrate git status
# Check what will be staged
polycrate git add --all
polycrate git commit -m "..."

Troubleshooting

"Authentication failed"

# Check whether the SSH key exists
ls -la artifacts/secrets/id_rsa

# Or in the root
ls -la id_rsa

# Check key permissions
chmod 600 artifacts/secrets/id_rsa

"Remote rejected"

# Pull first, then push
polycrate git pull
polycrate git push

"Local changes would be overwritten"

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

# Option 2: discard changes (CAUTION!)
git checkout -- .
polycrate git pull

See also