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 all major URL schemes for connecting with remote repositories:

• The file://... protocol does not support authentication. Note that you need to URL-escape any spaces in the URL with %20, e.g. file:///Volumes/my%20projects/...
• The git://... protocol also 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.
  Historically, there's also a "git+ssh" protocol; however, this is considered deprecated.

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:

• Private Key files added to the SSH agent
• Username/Password authentication configured with git-credential-osxkeychain (HTTP(S) and SSH) or .netrc (HTTP(S))

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

Authenticating with Username and Password

If the connection requires username and password, Tower will store a combination of password and remote URL in Mac OS' Keychain.app. If a matching Keychain item already exists, Tower can reuse it if you allow access to the Keychain item.

To securely access Keychain items, Tower provides an "Askpass" program. When a connection is trying to be made, this GIT_ASKPASS program is queried for the password.

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 in Keychain.

Note that this behavior is natively supported by the OS X ssh command; the Tower.app 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

You can manage your SSH public keys directly from within Tower: select the corresponding account in the Services view and activate the Public Keys tab.

1Password SSH keys

If you are using 1Password for storing your SSH keys, or plan to use it, read more about it at redesign-staging.git-tower.com/help/guides/integration/1password/mac:1Password%20SSH%20Integration.

Authenticating with GitHub, GitLab, Bitbucket and Other Hosted Repositories

Tower makes connecting to online services like GitHub, GitLab, Bitbucket, Azure DevOps, Perforce GitSwarm, and Beanstalk 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 coding hosting services 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-credential-osxkeychain

Tower transparently supports the use of the git-credential-osxkeychain helper.

This helper makes sure that credentials are conveniently & safely stored in Keychain.app. When using the default OS X system Git binary, this happens automatically (regardless of user configuration); when using a custom Git binary, the following configuration is necessary:

git config credential.helper osxkeychain

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

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

Additional Connection Options

Tower supports the http.sslverify and http.proxy settings from your global Git config. You can set this using the command line:

$ git config --global http.proxy PROXY

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. by using git-credential-osxkeychain or SSH key authentication (see above).