Git Sync Configuration

This page covers deploying and configuring Git Sync for the Query Library. For how sync works at runtime, see the Git Sync section on the Query Library page.

Setup

1. Create a Git Repository

Create a repository on GitHub, GitLab, Bitbucket, or any Git host. The repository should contain (or will be populated with) a queries/ directory.

2. Configure Authentication

The UI server needs write access to the repository. Choose one:

SSH key (recommended for servers):

# Generate a deploy key
ssh-keygen -t ed25519 -f /path/to/deploy-key -N ""

# Add the public key to your repository as a deploy key with write access
# Then configure the UI:
export UI_GIT_REPO="git@github.com:your-org/berserk-library.git"

HTTPS token:

export UI_GIT_REPO="https://github.com/your-org/berserk-library.git"
export UI_GIT_TOKEN="ghp_your_personal_access_token"

3. Configure the UI Server

export UI_LIBRARY_DIR="/data/library"       # Persistent directory
export UI_GIT_REPO="git@github.com:your-org/berserk-library.git"
export UI_GIT_BRANCH="main"                  # Optional, defaults to "main"
export UI_GIT_SYNC_INTERVAL_SECS="60"        # Optional, defaults to 60

On startup, the UI server:

Verifies that git is available (logs a clear error if not)
Clones the repository into UI_LIBRARY_DIR if the directory is empty
If the directory already has content (e.g. local seed files), initializes git in-place: git init, fetches the remote, and rebases local state onto it
Loads queries into memory and begins the sync loop

The YAML config file equivalent:

library_dir: "/data/library"
git_repo: "git@github.com:your-org/berserk-library.git"
git_branch: "main"
git_sync_interval_secs: 60

4. Kubernetes Deployment (Helm)

The Berserk UI container image already includes git and openssh-client. The Helm chart handles volume mounts and secrets.

Configure git sync in your Helm values:

ui:
  library:
    gitRepo: "https://github.com/your-org/berserk-library.git"
    gitToken: "ghp_your_personal_access_token"  # for HTTPS auth
    gitBranch: "main"                            # optional, defaults to "main"
    storage: "emptyDir"                          # "emptyDir" (default) or "pvc"

The chart automatically:

Mounts a writable volume at /library (emptyDir or PVC)
Sets UI_LIBRARY_DIR, UI_GIT_REPO, UI_GIT_BRANCH env vars
Creates a ui-library-git Secret for the token (if gitToken is set)

With git sync enabled, emptyDir is sufficient — the repository is cloned on every pod startup. Use storage: "pvc" only if running without git sync and you need queries to survive pod restarts.

For SSH key authentication, mount the key manually and use an SSH repo URL:

ui:
  library:
    gitRepo: "git@github.com:your-org/berserk-library.git"

Configuration Reference

Environment Variable	Default	Description
`UI_LIBRARY_DIR`	`./library`	Directory containing the library files
`UI_GIT_REPO`	(none)	Git repository URL for sync (enables Git Sync)
`UI_GIT_BRANCH`	`main`	Branch to sync with
`UI_GIT_SYNC_INTERVAL_SECS`	`60`	Polling interval for Git changes

All settings can also be provided in the YAML config file (without the UI_ prefix):

library_dir: "/data/library"
git_repo: "git@github.com:your-org/berserk-library.git"

Without UI_GIT_REPO (or when it is set to an empty/whitespace-only value), the library operates in file-only mode — queries are read from and written to UI_LIBRARY_DIR but not synced anywhere.

Local Development

For local development with mise ui-dev, the config at apps/ui/config/local2dev.yaml points to a test repo:

library_dir: "/tmp/berserk-library"
git_repo: "git@github.com:anagrius/berserk-library.git"
git_branch: "main"
git_sync_interval_secs: 30

The library directory is set outside the main repo to avoid git nesting issues. On first start, the repo is cloned into /tmp/berserk-library. To disable git sync for local work, set git_repo to an empty string or remove the line entirely — the library falls back to file-only mode reading from UI_LIBRARY_DIR.