Synchronization

Introduction

XPipe can synchronize all connection configuration data across multiple installations. It uses your own remote Git repository for that purpose. You can synchronize with this repository in all XPipe application instances. Every change you make in one instance will be reflected in the repository. This approach means that you have full control over your data, as you can freely choose how and where to host this repository.

First of all, you need to create a remote repository with your Git provider of choice. This repository must be private. Next, copy and paste the URL into the XPipe remote repository setting.

sync

Ensure that your repository visibility is set to private to prevent data leakage.

You don't have to link a remote repository. Just enabling git sync without one will create and maintain a local repository. This can be useful if you're looking for having a local history.

You also need to have a locally installed git client ready on your local machine. You can try running git --help in a local terminal to check. If you don't have one, you can visit https://git-scm.com to install git.

Authentication

There are multiple ways to authenticate. Most repositories use HTTPS where you have to specify a username and password. Some providers also support the SSH protocol, which is also supported by XPipe. If you use an SSH URL for git, you probably know how to configure it, so this section will cover HTTPS only.

You need to set up your git CLI to be able to authenticate with your remote git repository via HTTPS. There are multiple ways to do that. You can check if that is already done by clicking on the Test button below the remote repository URL in XPipe.

Many special tools like the GitHub CLI handle the whole authentication automatically for you when installed. Some newer git client versions can also authenticate via special web services where you just have to log in into your account in your browser.

There are also manual ways to authenticate via a username and token. Nowadays, most providers require a personal access token (PAT) to authenticate from the command-line instead of traditional passwords. You can find common (PAT) pages here:

GitHub: Personal access tokens (classic)
GitLab: Personal access token
BitBucket: Personal access token
Gitea: Settings -> Applications -> Manage Access Tokens section Set the token permission for repository to Read and Write. The rest of the token permissions can be set as Read. XPipe just needs enough permissions to commit changes to the private vault repository.

If XPipe asks you for your git login credentials every time, you need to configure your command-line git client if you don't want to enter them every time. You can use any git credentials manager for that. For more information, see for example:

If everything works out, XPipe should push a commit to your remote repository.

Syncing categories

By default, no connection categories are set to sync so that you have explicit control on what connections to commit. So at the start, your remote repository will be empty.

To have your connections of a category put inside your git repository, you need to click on the gear icon (when hovering over the category) in your Connections tab under the category overview on the left side. Then click on Add to git repository to sync the category and connections to your git repository. This will add all syncable connections to the git repository.

sync-add

Local connections

Any connection located under the local machine cannot be shared as it refers to connections and data that are only available on the local system.

Certain connections that are based on a local file, for example, SSH configs, can be shared via git if the underlying data, in this case the file, have been added to the git repository as well.

Adding files to git

When everything is set up, you have the option to add any additional files such as SSH keys to git as well. Next to every file choice is a git button that will add the file to the git repository. These files are also encrypted when pushed.

sync-file

GPG signing

If you have enabled GPG signing of your git commits, then this should work as expected. The only more complicated case is on Windows where you can have potentially two gpg executables with the git bash gpg and the native Gpg4win executable. By default, XPipe will choose the gpg client which has keys configured in it, under the assumption that you only use one of the two clients. If you switch between using both gpg clients, make sure that your git GPG key is available in gpg4win, as this client will be used if both clients have keys added.

Reverting to a previous commit

In case anything goes wrong are you just want to restore the vault at an earlier date, you can do so easily using the normal git reset functionality. The first step is to find the SHA of the commit you want to revert to. This will look like this: 42e2e5af9d49de268cd1fda3587788da4ace418a. You can find the commit SHA in any web interface of git your provider or on the command line with git log.

Once you have obtained the SHA, you can run the following commands:

cd "<User Home>/.xpipe/storage"
git reset --hard <SHA>
git push --force -u remote-storage HEAD

The push is required to overwrite the remote repository. Without the push, XPipe would just pull the changes from the remote repository again.