Connecting & Authenticating

Tower allows you to connect as many remote repositories with a local repo as you like. Simply click the + button on the bottom of the sidebar and choose Add Remote Repository….
You are then asked to enter the remote's URL and authentication information (if necessary).

Editing a Remote Connection

If you later want to check or edit the URL or authentication info, simply select the remote item in the sidebar.

Then, click the Edit button to the right of the "Fetch URL" field in the details view.

If you want to edit the default Fetch URL for a remote (which will be the case in most situations), you can use a shortcut: right-click the remote item in the sidebar and select Edit Connection Settings….

Supported URL Schemes

Tower supports these URL schemes for connecting with remote repositories:

• The git://... protocol does not support authentication.
• The http://... and https://... protocols support authentication. In case authentication is used, the username must be provided as part of the URL.
• The ssh://... protocol (also supported with its shorter, SCP-like syntax "user@host:path") requires authentication, either by providing username & password or via SSH key.

SSH Key Authentication
Learn more about SSH Key authentication (including how to create keys) in our learn section.

Authentication - With or Without User Interaction

Tower uses Git commands for connecting to a remote. If a remote Git command (e.g. "git fetch") works from the command line without user interaction, it will immediately work in Tower, too. The following authentication methods do not require user interaction for each call:

• Username/Password authentication configured with Git Credential Manager for Windows

If, on the other hand, a connection requires user interaction, you have to configure the remote connection in Tower once.

Using an existing SSH agent or Plink

Tower can support using Plink or an already running SSH agent. For both cases, please activate the "Use local SSH settings" flag in Tower's preferences.

For Plink the environment variable "GIT_SSH" needs to point to the "plink.exe".

For an existing SSH agent, the environment variable "SSH_AGENT_PID" needs to point to a process id, and the variable "SSH_AUTH_SOCK" must hold the authentication socket. Both pieces of information are displayed when starting the SSH agent.

Authenticating with Username and Password

If the connection requires username and password, Tower will store a combination of password and remote URL in it's credential manager if it isn't provided by other means, e.g. an ssh-agent or the Git Credential Manager for Windows.

The remote URL needs to contain the username, since connection information is derived from the URL: https://user@host/path/to/repo.git

Authenticating with SSH Keys

If you are already using SSH keys for authentication, there is nothing to configure - as long as your key is added to the local SSH agent.

Tower allows to assign a Private Key file per remote connection - in a very convenient way: Tower will pass the key file as -i KEYFILE to the ssh command. The -i option will automatically add it to the SSH agent for you. If your key is password-protected, it will also prompt you for the password and allow you to store the password for usage with a credential manager.

Note that this behavior is natively supported by the ssh command; Tower itself is not involved in this process. Tower will remember the chosen key file by saving it in the .git/config for the remote:

        [remote "origin"]
            gtPrivateKeyPath = ~/.ssh/keyfile

Authenticating with GitHub, Beanstalk and Bitbucket Repositories

Tower makes connecting to online services like GitHub, Beanstalk, and Bitbucket very easy.

You need to add your accounts to Tower's Services manager - because Tower uses this information for authentication. You only have to do this once (per account) and then don't have to reenter authentication for every repository any more.

Please note that SSH connections to GitHub, Beanstalk, and Bitbucket only work with SSH keys! The username for SSH service connections is always "git".

Specifying a Port Number

Port numbers for a connection can be specified in the URL itself - right after the hostname, separated by a colon: "ssh://user@someserver.com:2222/repo.git".

Note that if an SSH URL is in SCP syntax (user@someserver.com:repo.git), you cannot specify the port in the URL. You must either rewrite the URL to the standard SSH syntax or configure the port in your SSH config (see below).

SSH Configurations

Tower fully supports custom SSH configurations in your ~/.ssh/config file. This can be used to configure aliases for different connections or options for specific hosts, ports, and private key files. Below, we compiled a couple of examples.

Configuring port and username

    Host example.com
        Port 2220
        User foo

Using the URL "ssh://example.com/path/to/repo.git" would then connect as "ssh://foo@example.com:2220/path/to/repo.git".

Creating host aliases

    Host myserver
        HostName example.com
        Port 2220
        User foo

You can then use the following URL in Tower (or the command line): "ssh://myserver/path/to/repo.git".

Configuring a different SSH key for the same host

    Host github.com
        IdentityFile ~/.ssh/github.key

    Host github-org
        User git
        HostName github.com
        IdentityFile ~/.ssh/github.org.key

However, as mentioned above, you can also specify private key files in Tower per remote as well. The advantage of doing this in Tower is that there's no need to setup host aliases - with the disadvantage that it will only work with Tower.

Git Credentials Helper

Tower transparently supports the use of git-credential helpers.

This helper makes sure that credentials are conveniently & safely stored. Tower additionally provides a Tower_Askpass-helper, which tells git about the credentials stored with Tower.

Any connection configured with a git-credential helper will automatically work in Tower.

See git-scm.com/docs/gitcredentials.html for more details.

Submodule Authentication

Tower can handle only one authentication per call. Therefore, cloning or fetching a repository with submodules, e.g., will only succeed if all submodules use an authentication method that does not require any user interaction. This can be achieved e.g. SSH key authentication (see above).