The Git Credential Manager for Windows (GCM) provides secure Git credential storage for Windows. It's the successor to the Windows Credential Store for Git (git-credential-winstore), which is no longer maintained. Compared to Git's built-in credential storage for Windows (wincred), which provides single-factor authentication support working on any HTTP enabled Git repository, GCM provides multi-factor authentication support for Visual Studio Team Services and GitHub.
This project includes:
- Secure password storage in the Windows Credential Store
- Multi-factor authentication support for Visual Studio Team Services
- Two-factor authentication support for GitHub
- Personal Access Token generation and usage support for Visual Studio Team Services and GitHub
- Non-interactive mode support for Visual Studio Team Services backed by Azure Directory
- Optional settings for build agent optimization
This is a community project so feel free to contribute ideas, submit bugs, fix bugs, or code new features. For detailed information on how the GCM works go to the wiki.
To use the GCM, you can download the latest installer. To install, double-click Setup.exe and follow the instructions presented.
You don't. It magically works when credentials are needed. For example, when pushing to VSO, it automatically opens a window and initializes an oauth2 flow to get your token.
Note for users with special installation needs, you can still extract the gcm-<version>.zip file and run install.cmd from an administrator command prompt. This allows specification of the installation options explained below.
To build and install the GCM yourself, clone the sources, open the solution file in Visual Studio, and build the solution. All necessary components will be copied from the build output locations into a .\Deploy folder at the root of the solution. From an elevated command prompt in the .\Deploy folder issue the following command git-credential-manager install.
Various options are available for uniquely configured systems, like automated build systems. For systems with a non-standard placement of Git use the --path <git> parameter to supply where Git is located and thus where the GCM should be deployed to. For systems looking to avoid checking for the Microsoft .NET Framework and other similar prerequisites use the --force option. For systems looking for silent installation without any prompts, use the --passive option.
Frequently asked questions collected from our issues page, our twitter feed, and other sources. Please look through this list of questions-and-answers before posting a new issue on a topic.
Most likely, your environment is not configured correctly. You can verify that you’re environment is configured correctly by running git config --list and looking for credential.helper=manager. If you do not see the line, then you know that Git does not know about the Git Credential Manager. You can configure Git to use the Credential Manager by running git config credential.helper manager.
Most likely reason is that your GUI “shells out” to git.exe to perform Git operations. When it does so, it cannot respond to the command line prompts for username and password like a real user can. To avoid being asked for your credentials on the command line, and instead be asked via a modal dialog you’ll need to configure the Credential Manager.
-
Decide if you want this to be a global setting (all of your repos) or a local setting (just one repo).
-
Start your favorite shell. (cmd, powershell, bash, etc.)
-
Update your settings, so that Git Credential Manager knows to display a dialog and not prompt at the command line:
-
If you’ve decided this is a global setting run
git config --global credential.modalprompt true. -
If you’ve decided this a per repo setting,
cdto your repo and in that repo rungit config credential.modalprompt true.
-
The Git Credential Manager does not yet support secure storage for SSH keys. It is something we hope to implement, but it has not been a priority. If you feel otherwise, please commend on the SSH Key support issue which is already open.
The Git Credential Manager does not work on Windows XP, Max OS, or Linux because we had to scope our work and we decided to support the same operating systems that Visual Studio support. Why Visual Studio? Well, because it is our favorite IDE and in order to support Visual Studio Team Services we had to use the Azure Directory Authentication Libraries which only have multi-factor interactive logon support in their .NET libraries. Using .NET means using Visual Studio (which we love anyways) and using Visual Studio means Windows 7 or newer.
We can safely say that we have no interest in supporting Windows XP. Even Microsoft has ended support for Windows XP. Support for Mac OS and Linux are very much something that we’re interesting in. We’re looking at options with .NET Foundation cross-platform support and ADAL Node.js support. Neither option is ready for a security application, and we’re not ready to port yet -- let’s at least get the ‘for Windows’ version to version 1.0 first!
The Credential Manager deployment helpers (install.cmd and Setup.exe) are focused on support for Git for Windows because Git for Windows conforms to the expected/normal behavior of software on Windows. It is easy to detect, has predictable installation location, etc. This makes supporting it cheaper and more reliable.
That said, so long as your favorite version of Git supports Git’s git-credential flow, it is supported by the Git Credential Manager for Windows. Setup will have to be manual, and if you find a way to script it we would love to have you contribute that to our project.
-
Copy the contents of the
gcm-<version>.zipto your Git’s /bin folder. This varies per distribution, but it is likely next to other git tools likegit-status.exe. -
Update your Git configuration by running
git config --global credential.helper manager.
Build agents cannot manage modal dialogs, therefore we recommended the following configuration.
git config --global credential.interactive never
Build agents often need to minimize the amount of network traffic they generate.
To avoid Microsoft Account vs. Azure Active Directory look-up against a Visual Studio Team Services account use:
git config --global credential.authority Azure
To avoid unnecessary service account credential validation use:
git config --global credential.validate false
There are many ways to contribue.
-
Submit bugs and help us verify fixes as they are checked in.
-
Review code changes.
-
Contribute bug fixes and features.
For code contributions, you will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you grant us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under the appropriate copyright.
Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign digitally. Alternatively, download the agreement Microsoft Contribution License Agreement.pdf, sign, scan, and email it back to cla@microsoft.com. Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request.
To enable logging, use the following:
git config --global credential.writelog true
Log files will be written to the repo's local .git/ folder.
This project uses the MIT License.