Skip to main content

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 have access to.

The default, and currently recommended, way to interact with repositories is using their HTTPS URL. For example:

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

Worktree currently does not support alternative access methods, such as SSH. This is planned for the future; subscribe to this issue if you are interested.

Create an Access Token​

To authenticate with Worktree, you will need to create an Access Token for your computer.

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

Dropdown menu showing "Settings" highlighted

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".

Screenshot of the token creation form indicating which fields to fill out.

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.

Screenshot of an access token being shown.

Configure Git​

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

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