SourceTree for Windows 1.10.0-* authentication and accounts updates

Still need help?

The Atlassian Community is here for you.

Ask the community

We've added a lot to our latest update and we need your help to get all this new goodness installed.

To install the new version of SourceTree:

  1. Open SourceTree.
  2. Click Help>Check for Updates and install the latest updates for your current version of SourceTree (udates your version to SourceTree_1.9).
  3. Close  version SourceTree_1.9.
  4. Go to: https://sourcetreeapp.com/
  5. Click the download link to get the latest 1.10.x installer.
  6. Run the 1.10.x installer.
  7. Uninstall SourceTree_1.9.

You can also reference the most recent Release Notes.

You can downgrade to a previous version if you kept the old installer. However, due to the new installer, configuration files may not be backwards compatible.

This page

Related pages

  • Related page

 What you get with this newer version

We added the following:

  • A new simplified install and update process, so you always get all the latest features, patches, and fixes.
  • OAuth authentication support
  • Two-step authentication support
  • New Git Credential Manager for Windows
  • Custom SSH_ASKPASS implementation for Mercurial that supports Bitbucket basic auth and OAuth
New installer details...

The new installation process is much simpler and changes where SourceTree is installed. Moving the installed location from %ProgramFiles(x86)%\Atlassian\SourceTree to %localappdata%\SourceTree means SourceTree is installed per user, rather than per machine. With this update you'll no longer need Admin rights during installation, so the update process will be much less intrusive.

The new installers also support progressive feature rollouts so we can ship new features to a subset of users, monitor for any regressions, address anything that is found, and then roll the feature out to all users. This will be a great help in providing a more stable experience for users.

More about the authentication changes

Currently SourceTree only supports  Basic Auth credentials for communication with Bitbucket and GitHub services. This is true for Git, Mercurial, and REST API calls. Both Bitbucket and GitHub recommend the use of Two Factor Authentication (2FA) to secure your accounts. Unfortunately, the use of two-step authentication prevents the use of Basic Auth for authentication. Which meant switching to SSH for Git and Mercurial URL's. While this works, SSH is still a little strange in a Windows environment.

A new Git Credentials Manager

The new Git Credential Manager for Windows (GCM), developed by Microsoft, adds support for retrieving and using OAuth tokens for use with Visual Studio Team Services, Team Foundation Server, and GitHub.

The use of OAuth means it is now possible to support HTTPS URLs while using a 2FA protected account. Additionally the GCM also manages credentials using Windows Credentials Manager, or Vault, a secure part of the Windows OS.

Click here to learn why this matters for this update

SourceTree and Bitbucket have not been able to take full advantage of these improvements: the current release of the GCM does not support Bitbucket OAuth for HTTPS URLs and SourceTree has not supported OAuth for git/hg or REST API calls. This has meant, when using SourceTree, you have the following choices:

  • don't use 2FA with Bitbucket and GitHub and continue to use Basic Auth for HTTPS git/hg URLs and REST API calls.
  • use 2FA on Bitbucket and GitHub, but rely on SSH for git/hg interactions and do without REST API calls at all.

SourceTree 1.10 begins to address this problem by:

  • Migrating its credentials storage to Windows Credentials Manager.
  • Supporting OAuth credentials for Accounts created in SourceTree
  • Providing a custom implementation of GCM that supports Bitbucket Basic Auth and OAuth
  • Providing a custom SSH_ASKPASS implementation for use with hg that supports Bitbucket Basic Auth and OAuth

Windows Credentials Manager support and OAuth

We made considerable changes to Account creation and management in SourceTree to support OAuth and the Windows Credentials Manager.

We've removed the Account editing dialog in Edit Accounts (in the View>Show Hosted Repositories section).  Then we updated the Authentication tab (in the Tools>Options section).

New authentication tab

You can now manage your accounts and authentication methods in this one consolidated tab:

Notice:

  • The new Accounts section.
  • The authentication method is listed now (in this example it is listed as OAuth).
  • The Saved Passwords section.
  • The ability to set a default account (in this example you can see bitbucket.org: No showing that Bitbucket is not set as the default).
  • The additional accounts listed below. 

Screen capture of SourceTree Authentication tab

In the Edit hosting account section you'll see:

  • The ability to select authentication methods.
  • A new Refresh OAuth Token button.

New managed accounts section

The Authentication tab lists your SourceTree managed accounts. We store credentials for these accounts in the Windows Credentials Manager. This makes them available for REST API calls and Git/Mercurial interactions through both the standard and SourceTree's custom Git Credentials Manager (GCM).

It is also possible to set an account as the default for a hosting service like Bitbucket. This means SorceTree uses these credentials (the username and Basic Auth password or OAuth token) when no username is specified in a Mercurial or Git URL.

Saved passwords section

Saved Passwords is a list of other credentials stored in the Windows Credentials Manager which are available for Git and Mercurial interactions via the standard GCM and SourceTree's custom GCM. These can be Basic Auth or OAuth credentials. Credentials can be deleted. Basic Auth Credentials can be edited, meaning you can change the password.

tip/resting Created with Sketch.

You can define existing credentials as the default for a given Host.

Host level credentials are named with the Host DOMAIN alone, where as user specific credentials are named USERNAME@DOMAIN

Path parameters and other directory and install details

Click to see install and path parameter details

The standard Git Credentials Manager ships with Git for Windows releases. This is installed in

{GIT_INSTALL_FOLDER}\mingw32\libexec\git-core folder as git-credential-manager.exe

It is referenced by git via the credential.helper git config setting, see https://git-scm.com/docs/gitcredentials

The SourceTree customization of GCM is installed into

%localappdata%/SourceTree-Settings/beta/git_extras 

as git-credential-manager-st.exe.

SourceTree is able to use this version by adding

%localappdata%/SourceTree-Settings/beta/git_extras 

to the PATH environment variable before running any git commands and by including the following command parameter to every git command

-c credential.helper=manager-st


The user is only prompted if neither the standard nor the customized GCM can provide suitable valid credentials.

Mercurial support

In order to give Mercurial calls access to the same credentials SourceTree installs, into %localappdata%\SourceTree-Settings\Beta\hg_extras, st-askpass-gcmpassthrough.exe. This is a simple executable that is able to take SSH_ASKPASS requests generated by Mercurial calls and convert them into calls to the custom GCM. SourceTree makes use of this by setting the SSH_ASKPASS environment variable to point at st-askpass-gcmpassthrough.exe before every Mercurial call.

Known Issues

  • OAuth credentials listed in the Authenticaion tab, under Saved Passwords, cannot be edited.
  • The custom GCM is not available from the SourceTree Terminal or your own command line currently. Because this is the case, the custom GCM it will not be able to refresh OAUth tokens when they expire. This is the case even though the standard GCM should be able to access credentials created by the custom GCM.
  • The standard and custom GCMs only support a single GitHub account at a time.
  • Some of the messaging around error handling may be a little obscure at the moment, we are continuing to work on this to clarify our error messaging.

 

Last modified on Jan 18, 2017

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.