Git integration authentication tokens

This page describes the Git authentication token login method for accessing your projects through Overleaf's Git integration. The authentication token method described here is the only login method available for both Overleaf Cloud and Server Pro. The older username and password-based authentication method is no longer available.

The Overleaf Git integration allows you to clone your Overleaf project to a local repository, treating your Overleaf project as a remote repository that changes can be pushed to and pulled from.

Summary

To perform Git operations on an Overleaf project using Git, you’ll need to authenticate as the owner of the project or as a collaborator. You can do this using a Git authentication token. You can create and delete authentication tokens in your Overleaf Account Settings.

• If prompted for a username, enter the username “git”
• When prompted for a password, enter your authentication token
• The same authentication token can be used to access all your projects using Git
• Tokens that you generate should be used exclusively by you and and stored securely

When performing Git operations, use the username git and use the authentication token as the password. The same authentication token can be used to access all your projects using Git. Tokens that you generate should be used exclusively by you and and stored securely. You can create and delete authentication tokens on your Overleaf Account Settings page.

Step-by-step: How to clone a project using Overleaf Git authentication tokens

The following steps explain how to clone your Overleaf project when using the Git command line.

If you’re using another Git client, you can use a method appropriate for the client to provide the Git URL for the project, "git" as the username, and the Git authentication token as the password. See Understanding the Git URL for an explanation of the components of the Git URL.

1. Select Git from the the Menu within your project.

1. Copy the git clone command and URL displayed in the dialog box. You will use this when creating your local repository.
2. Paste the command and URL into a command prompt. Note that "git" is provided as the user name in the provided command.
3. Get your Git authentication token
   • If you’ve not created a Git authentication token before, you’ll be given the option to generate one now. To do so, click Generate token.
   • If you’ve already created a Git authentication token you can use the same one or generate a new one in your Overleaf Account Settings. Top tip: You can set up Git credential helpers so that you don’t need to provide a token every time.
4. When prompted for a password, enter your authentication token.

Step-by-step: How to update the Git remote URL from password based format to authentication tokens

The following steps explain how to update the Git remote URL from the previous password-based format to the new authentication token-based format.

1. Open your terminal and navigate to your project's directory:

cd path/to/your/project

2. Check your current remote URL:

git remote -v

This will display the current URL(s) for your remote(s).

3. Update the remote URL using the following command:

git remote set-url origin https://git@git.overleaf.com/<YOUR_PROJECT_ID>

Replace it with your project ID

4. Verify that the change was successful by running the remote command again:

git remote -v

You should now see the new URL listed.

On the next pull or push from this local repository, you will need to provide an authentication token as the password. If you have not already generated an authentication token, you can do this from your Account Settings. When using auth tokens, if prompted for a user name, use "git" and the authentication token as the password - you can avoid providing these credentials on each operation by using a credential helper (see note below).

More help with authentication tokens

Understanding Overleaf Git authentication tokens

• Like a password, a Git authentication token can be provided to a Git operation to confirm your identity. In the same way you wouldn’t share a password, you should never share your authentication tokens.
• The authentication tokens you generate can be used across all the projects you’re accessing using the Git integration.
• Tokens will expire after one year.
• You can have a maximum of 10 tokens. If you reach your 10 token limit, you should delete old unused or expired tokens in order to create a new token.
• We recommend using Git credential helper to store your authentication token, so you don’t have to enter it every time you use the Git integration. There’s more information on how to set this up below.

How to generate authentication tokens

• You can review and generate Git authentication tokens in your Account Settings. You can generate up to 10 tokens.
• The first time you use the Git integration, you will also have the option to generate a token directly from a project when you select Git in the project Menu.

How to save your token using Git credential helpers

We recommend using a Git credential helper. This will allow your Git client to remember your token.

If you’re using the Git command line client, you can run this command to store your credentials:

$ git config --global credential.helper store

There’s more information about this on this Git documentation page.

Viewing previously generated tokens

You can find a list of your Git authentication tokens in your Account Settings. However, you won’t be able to view the whole token. If you can’t remember your token, and don’t have Git credential helpers enabled, you’ll need to generate a new one. You can do that in your Account Settings.

Deleting a generated token

When a token is deleted, it can no longer be used to authenticate your identity when performing Git operations. If you attempt an operation with an expired or deleted token, you will likely see an authentication error reported by your Git client.

How to work with collaborators

If you’re using Overleaf's Git integration to collaborate with someone who doesn’t normally use Overleaf, you should share the project with them and they can create an Overleaf account. Once they have done this, they can obtain the Git URL for the project and generate their own token in order to access the project.

You should never share a token. Treat it as securely as a username and password. If you feel that you have accidentally shared a token, you should delete it.

Understanding the Git URL

The git clone and Git URL can be obtained by selecting Git in the project Menu. Alternatively, you can find the Git URL from the project url (the url in the browser address bar when you are in a project).

Overleaf Cloud

If your Overleaf project url looks like:

https://www.overleaf.com/project/1234567

Then the Git url to use to clone the project will be:

https://git.overleaf.com/1234567

Your username will be git and the password will be the token you obtain from your Overleaf account.

The command and URL provided on the Git modal in the project Menu consists of: (1) the git clone command used at the Git command line and (2) the full Git URL that includes the project id prepended with the "git" user name.

Overleaf Server Pro

If your Overleaf project url looks like:

 https://<SHARELATEX_SITE_URL>/project/1234567

Note: The <SHARELATEX_SITE_URL> is the host value set by your Overleaf Server Pro administrator.

Then the Git url to use to clone the project will be:

https://<SHARELATEX_SITE_URL>/git/1234567

Your username will be git and the password will the token you obtain from your Overleaf account.

The command and URL provided on the Git modal in the project Menu consists of: (1) the git clone command used at the Git command line and (2) the full Git URL including the "git" user name, your specific Overleaf host, and a path that includes the project id.