Save your settings to GitHub

Git sync keeps a copy of your server's settings in a repository that belongs to you. Every time something changes, a new save is added to the history. It has two uses:

• If your AI, a plugin or you make a change you do not want, you can go back to an earlier save.
• You keep a copy of your settings away from our machines.

This page walks through GitHub step by step. GitLab and Codeberg are covered in short at the end. Any other host that supports deploy keys with write access works the same way.

What you need

• A free account on GitHub (or GitLab or Codeberg).
• You must be the owner of the server. Team members cannot connect a repository.

Step 1: Create a private repository

1. In GitHub, choose New repository.
2. Give it any name, for example my-server.
3. Choose Private.
4. Leave the options for a README, .gitignore and licence turned off. An empty repository is best.
5. Choose Create repository.

A private repository can only be read by you and the people you invite. A public repository can be read by anyone on the internet. We warn you before the first save if the repository is public, but we still allow it. We hide passwords and keys we know about, but plugin settings can say a lot about your server, so private is the safer choice.

Step 2: Open the Git sync page

1. In the panel, open your server.
2. Open Git sync.
3. Choose Connect. You may be asked to confirm it is you.

Step 3: Paste the SSH address

1. On your repository page in GitHub, choose Code, then SSH.
2. Copy the address. It looks like [email protected]:your-name/my-server.git.
3. Paste it into the panel and choose Continue.

The panel shows the branch it will write to. It is named quarry/<your-server-name>. We only write to that branch. Your other branches are never touched.

Step 4: Confirm the host

For GitHub, GitLab and Codeberg we already know the host, so there is nothing to confirm. For any other host, the panel shows the host's fingerprint once. Compare it with the one your host publishes, and choose to confirm it. We check it again on every save after that.

Step 5: Copy the deploy key

The panel creates a new key just for this server and this repository, and shows the public half with a Copy button. Copy it. The private half stays with us, is stored encrypted, and is never shown to anyone.

Step 6: Add the key in GitHub, with write access

1. In your repository on GitHub, open Settings.
2. In the left menu, choose Deploy keys.
3. Choose Add deploy key.
4. Give it a title such as server saves, and paste the key.
5. Tick Allow write access. Without this, we cannot save anything.
6. Choose Add key.

Step 7: Check the connection

Back in the panel, choose Check connection. We make a small test save on a temporary branch and delete it again. If it works, the connection is marked as verified and the first full save begins.

If it does not work, the panel says why in plain words. See "If something goes wrong" below.

What gets saved

Settings and the things that describe your server:

• Server settings such as server.properties, and the other main settings files.
• Plugin settings files.
• Mod settings in the config folder.
• Data packs (unpacked).
• Scripts that plugins read, such as Skript scripts.
• A list of your software, version and installed plugins and mods, with their versions.

What is never saved

• Worlds.
• Plugin and mod files (the .jar files). Only their names and versions are listed.
• Player data: inventories, stats, ops, bans, the whitelist and chat.
• Logs and crash reports.
• Databases.
• Passwords, keys and tokens. Any value that looks like one is replaced with QUARRY_HIDDEN. The values our own system holds, such as the secret between your server and our network, are never included at all.

If a file looks like it holds a password or key that we did not recognise, the save stops and tells you which file and line. Hide that setting or exclude that file, and the save continues. You can add your own files and setting names to hide on the Git sync page. You can add to our list but never remove from it.

How saving works

A new save is made after each change made through the panel, the file editor or your AI. Changes made by a plugin, over SFTP or by the server itself are picked up about every 15 minutes while the server runs. Each save has a plain description, for example "AI connector (Claude): changed server.properties (max-players, motd)".

We only add to the quarry/<your-server-name> branch and never overwrite it. If someone else pushes to that branch, saving pauses. The panel asks you not to push to that branch: delete it on your repo host, then press Sync now.

Go back to an earlier save

1. Open Git sync and look at History. Each entry is a change we sent to your repository.
2. Choose View changes on a save to see what would change, file by file.
3. Choose Restore, then confirm in the Restore this save? box.

A snapshot of the server as it is now is taken first, so you can undo the restore. Passwords and keys keep their current values and are never replaced with QUARRY_HIDDEN. If a hidden value in the save cannot be filled in from the server now, the panel lists it under Kept as they are: set these by hand. Some files are never restored because they are outside what we save, too big or protected, and the panel lists those too. After a restore, restart the server so the settings take effect.

If the save lists plugin versions, a card asks This save had these plugin versions: reinstall them? Each one goes through the normal install, with its usual checks. Plugins that cannot be reinstalled from there are listed separately. Choose Reinstall them, or Not now. Nothing is reinstalled without your choice.

The owner can restore. A team member can restore if their role has the Restore from git permission.

Let your AI use the history

There is a setting, Let my AI use the Git history, which is off until you turn it on. Only the owner can change it. When it is on, your AI can read earlier versions of your settings and put one back, following your Allow, Ask and Block settings on the AI page. Restoring starts as Ask, and a restore that puts settings files back also waits for your tap (see Set up once, then build with your AI). Your AI can never connect, disconnect or change the repository, and can never change this setting. See also Set up once, then build with your AI.

Change the key or disconnect

• New key: choose Make a new key, add it in GitHub the same way, check it, and then remove the old key from GitHub.
• Disconnect: the stored key is deleted at once and saving stops. Remove the deploy key from GitHub as well. The history we keep for restores stays for 30 days and is then deleted.

If something goes wrong

• "The key has no write access." In GitHub, open the deploy key and make sure Allow write access is ticked. If it is not, delete the key, add it again and tick the box.
• "That repo wasn't found." Check the address. Copy it again from Code, SSH. A deploy key only works on the repository it was added to.
• "We couldn't reach that host." Try again in a few minutes. If it keeps failing, check the host's status page.
• "The key was removed or lost write access." Saving pauses. Add a new key and check the connection again.
• A save was stopped because a line looks like a password. The panel names the file and line. Hide that setting or exclude the file.
• Changes are waiting. If the host is down, saves are kept and sent when it is back. After three days of failing, saving pauses and we email you once.
• Someone else changed the branch. We never overwrite it. Delete that branch on your repo host, then press Sync now.

GitLab

1. Create a private project with no README.
2. Copy the SSH address from Code, then Clone with SSH.
3. Paste it in the panel and copy the deploy key.
4. In the project, open Settings, then Repository, then Deploy keys, and add the key.
5. Tick Grant write permissions to this key.
6. Back in the panel, choose Check connection.

Codeberg

1. Create a private repository with no README.
2. Copy the SSH address from the repository page.
3. Paste it in the panel and copy the deploy key.
4. In the repository, open Settings, then Deploy keys, and add the key.
5. Untick Read-only, so the key can write.
6. Back in the panel, choose Check connection.

Other hosts

Use the host's SSH address, confirm the fingerprint once, and add the key as a deploy key with write access. If your host does not offer deploy keys with write access, Git sync cannot use it.