Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

Use this file to discover all available pages before exploring further.

The GitOps extension brings version-controlled configuration management to Universe. It clones a Git repository at startup, then pulls updates on a configurable interval, copying the repo’s templates/ and configuration/ directories into the live Universe directories after each pull. No native git binary is required — the extension uses JGit 7.6.0 for pure-Java Git operations.

​
When to Use This

  • You want version history and pull-request reviews for changes to templates and instance configurations.
  • You run a CI/CD pipeline that builds server JARs or configuration files and pushes them to a Git repository.
  • You need automated rollouts when changes land on a branch — Universe will pick them up within intervalMs milliseconds.

​
How It Works

1

Clone on startup

On onLoad(), the extension clones the configured repository to targetPath (default: ./git-sync). If the directory already exists and contains a valid Git repository, it opens it in place instead of cloning again.
2

Scheduled pull

A single-threaded scheduled executor fires every intervalMs milliseconds and runs a Git pull against the configured branch.
3

File copy

After each successful pull, the extension copies {targetPath}/templates/ to ./templates/ and {targetPath}/configuration/ to ./configuration/, overwriting any existing local files.

​
Configuration

Create ./extensions/gitops/config.json: 
{
  "url": "https://github.com/your-org/universe-config.git",
  "branch": "main",
  "targetPath": "./git-sync",
  "intervalMs": 300000,
  "enabled": true,
  "username": "",
  "password": "",
  "sshKeyPath": ""
}
FieldDefaultDescription
url""Git repository URL (HTTPS or SSH git@ format)
branch"main"Branch to track
targetPath"./git-sync"Local directory where the repository is cloned
intervalMs300000Pull interval in milliseconds (default: 5 minutes)
enabledfalseMust be true for syncing to be active
username""HTTP Basic Auth username for private HTTPS repositories
password""HTTP Basic Auth password or personal access token
sshKeyPath""Path to an SSH private key file for git@ URLs

​
Repository Structure

Your Git repository must mirror the Universe directory layout: 
universe-config/
  templates/
    server/
      base/
        server.properties
        plugins/
    lobby/
      default/
        server.properties
        world/
  configuration/
    lobby.json
    minigames.json
The extension copies templates/ and configuration/ as top-level directories. Files outside these two directories in the repository are ignored.

​
Authentication Examples

Use a GitHub (or GitLab) personal access token as the password field:
{
  "url": "https://github.com/your-org/universe-config.git",
  "branch": "main",
  "username": "your-github-username",
  "password": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "enabled": true
}

​
Manual Sync

The extension syncs automatically on its configured interval. To force an immediate sync without restarting Universe, trigger a reload: 
extension reload gitops
Or via the REST API: 
curl -X POST http://localhost:7000/api/commands/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "extension reload gitops"}'
onReload() re-pulls the latest commits and copies files immediately, then continues the background schedule as before.
GitOps overwrites local files on every pull. Any changes you make directly to ./templates/ or ./configuration/ will be lost the next time the extension syncs. Treat the Git repository as the single source of truth and make all changes there.

Build docs developers (and LLMs) love

Get started for freeTalk to us