Authenticating with Git

To clone, push, or pull changes from a repository in Worktree, you need to authenticate so we know who you are and can verify which repositories you can access.

Note: authenticating with Git is only required when setting up your own computer and devices, and gives full access to all your repositories. NEVER grant anyone else access to your Worktree account, or authorize SSH keys you don't personally control.

Authenticate Using SSH Keys (Recommended)

The recommended method is to use SSH connections with an SSH keypair. This is the most secure option, and also is the easiest to get set up.

1. Generating an SSH Keypair

If you don't already have an SSH keypair, generate one with the ssh command line utility, ssh-keygen.

There are multiple different types of keys, all using different strengths and types of encryption. We recommend generating an "ED25519" key, which is more modern option; however, the default remains RSA, which is older but still plenty secure for general use. Worktree supports both RSA and EC SSH key algorithms, so it is your choice.

To generate a key, use ssh-keygen and follow the prompts it asks you. The defaults should be fine, if in doubt. Your output should look similar to below:

$ ssh-keygen -t ed25519
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ~/.ssh/id_ed25519
Your public key has been saved in ~/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:4DMylRl5VNmEb4JCJnjkj68gqvqkJrzCLUPBjDiQxDk ablackie@monarch.yul-1.blackie.ca
The key's randomart image is:
+--[ED25519 256]--+
|oo.o. .o...=.    |
|oE..o ++. o .    |
|* ...+=. . .     |
|++   =... . o    |
| .. + =.S  o     |
| .   + o         |
|= +   .          |
|+X o .           |
|@o= .            |
+----[SHA256]-----+

2. Import your SSH public key

With your SSH keypair in hand, you can now import it into your Worktree account to use for authentication.

Click on your profile picture in the top right and go to "Settings".

From there go to "SSH / GPG Keys" in the menu on the left.

Here, click "Add Key", and paste in the public key generated by ssh-keygen (the one ending in ".pub").

That should be all that is required to access Git repositories over SSH in Worktree!

---

Authenticate Using HTTPS

If you can't or don't want to use SSH keys to authenticate with Worktree, another method is by using their HTTPS URL. For example:

https://worktree.ca/worktree/docs.git

This method requires you to use a username and Access Token to authenticate.

1. Create an Access Token

To authenticate over HTTPS, you will need to create an Access Token for your computer.

Go to your account settings from the user menu in the top-right:

From here, navigate to "Applications" in the menu on the left. In the "Manage Access Tokens" box, fill out a new token name, and select "Read and Write" permissions for "repository".

Click "Generate Token".

A notice box will appear at the top of the page containing your API token. Copy and save this token, as it will not be shown again.

2. Configure Git

Now that we have an access token, we need to configure Git to use it when interacting with worktree.ca.

Option 1: Use a secure credential manager (recommended)

The most secure option is to use a credential manager plugin for Git to securely store credentials in an encrypted vault.

There are many tools to do this, but a common and easy-to-use option is git-credential-manager.

Follow the installation guide for git-credential-manager to get it installed.

Then, the next time you git push or git clone from Worktree, you'll be prompted for your username and password. Use your access token that we created previously as your password. git-credential-manager will save your credentials securely (eg., in the macOS Keychain) and reuse them in the future automatically.

Option 2: Use Git's default credential manager

Git comes with a default credential manager called store, which you could use instead of a third-party option like git-credential-manager.

The default Git credential store simply logs credentials in ~/.git-credentials in plain-text. This is not ideal as it leaves sensitive secret values in a well-known location, which could be a security risk depending on your IT policies or if your computer is shared.

However, it is the easiest to configure. Add the following snippet to the bottom of your ~/.gitconfig file:

[credential]
    helper = store

Once added, the next time you provide credentials to Git, it will store them and reuse them for subsequent commands.

Option 3: Configure .netrc

A less secure option is to hard-code credentials in a .netrc configuration file, which Git will use. This stores your access token in plain text in the file, which may be a security risk on shared computers (or if your computer gets compromised).

On macOS and Linux, the file is ~/.netrc file. On Windows, the file to create is called %HOME%\_netrc.

In your text editor, create a file in your home directory at ~/.netrc, and add your username and access token. For example:

machine worktree.ca
	login alex
	password c3faab852a8f33e0095d7099721ecd80171eeae1