Connecting & Authenticating
Tower allows you to connect as many remote repositories with a local repo as you like. Simply click the
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 thebutton 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.
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 theview and activate the tab.
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 "
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://firstname.lastname@example.org:2222/repo.git".
Note that if an SSH URL is in SCP syntax (email@example.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).
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://firstname.lastname@example.org: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.
Tower transparently supports the use of the
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.proxy settings from your global Git config. You can set this using the command line:
$ git config --global http.proxy PROXY
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).