The Git Credential Manager for Windows (GCM) provides secure Git credential storage for Windows. GCM provides multi-factor authentication support for Azure DevOps, Team Foundation Server, GitHub, and BitBucket.
After installation, Git will use the Git Credential Manager for Windows and you will only need to interact with any authentication dialogs asking for credentials. The GCM stays invisible as much as possible, so ideally you’ll forget that you’re depending on GCM at all.
Assuming the GCM has been installed, using your favorite Windows console (Command Prompt, PowerShell, ConEmu, etc.), use the following command to interact directly with the GCM.
git credential-manager [<command> [<args>]]Removes stored credentials for a given URL. Any future attempts to authenticate with the remote will require authentication steps to be completed again.
This method is being deprecated and users should use “git credential reject” instead
Deploys the Git Credential Manager for Windows package and sets Git configuration to use the helper.
Specifies a path (<installation_path>) for the installer to deploy to. If a path is provided, the installer will not seek additional Git installations to modify.
Instructs the installer to not prompt the user for input during deployment and restricts output to error messages only.
When combined with --force all output is eliminated; only the return code can be used to validate success.
Instructs the installer to proceed with deployment even if prerequisites are not met or errors are encountered.
When combined with --passive all output is eliminated; only the return code can be used to validate success.
Removes the Git Credential Manager for Windows package and unsets Git configuration to no longer use the helper.
Specifies a path (<installation_path>) for the installer to remove from. If a path is provided, the installer will not seek additional Git installations to modify.
Instructs the installer to not prompt the user for input during removal and restricts output to error messages only.
When combined with --force all output is eliminated; only the return code can be used to validate success.
Instructs the installer to proceed with removal even if prerequisites are not met or errors are encountered.
When combined with --passive all output is eliminated; only the return code can be used to validate success.
Displays the current version.
Synonym for delete.
Synonym for deploy.
Synonym for remove.
Commands for interaction with Git.
Git Credential Manager and Git Askpass work out of the box for most users. Configuration options are available to customize or tweak behavior(s).
The Git Credential Manager for Windows [GCM] can be configured using Git’s configuration files, and follows all of the same rules Git does when consuming the files. Global configuration settings override system configuration settings, and local configuration settings override global settings; and because the configuration details exist within Git’s configuration files you can use Git’s git config utility to set, unset, and alter the setting values.
The GCM honors several levels of settings, in addition to the standard local > global > system tiering Git uses. Since the GCM is HTTPS based, it’ll also honor URL specific settings. Regardless, all of the GCM’s configuration settings begin with the term credential. Additionally, the GCM respects GCM specific environment variables as well.
Regardless, the GCM will only be used by Git if the GCM is installed and the key/value pair credential.helper manager is present in Git’s configuration.
For example:
credential.microsoft.visualstudio.com.namespaceis more specific thancredential.visualstudio.com.namespace, which is more specific thancredential.namespace.
In the examples above, the credential.namespace setting would affect any remote repository; the credential.visualstudio.com.namespace would affect any remote repository in the domain, and/or any subdomain (including www.) of, ‘visualstudio.com’; where as the the credential.microsoft.visualstudio.com.namespace setting would only be applied to remote repositories hosted at ‘microsoft.visualstudio.com’.
For the complete list of settings the GCM understands, see the list below.
Defines the type of authentication to be used.
Supports Auto, Basic, AAD, MSA, GitHub, Bitbucket, Integrated, and NTLM.
Use AAD or MSA if the host is ‘visualstudio.com’ Azure Domain or Live Account authentication, relatively.
Use GitHub if the host is ‘github.com’.
Use BitBucket or Atlassian if the host is ‘bitbucket.org’.
Use Integrated or NTLM if the host is a Team Foundation, or other NTLM authentication based, server.
Defaults to Auto.
git config --global credential.microsoft.visualstudio.com.authority AADSee GCM_AUTHORITY
Causes the proxy value to be considered when evaluating credential target information. A proxy setting should established if use of a proxy is required to interact with Git remotes.
The value should the URL of the proxy server.
Defaults to not using a proxy server.
git config --global credential.github.com.httpProxy https://myproxy:8080See HTTP_PROXY
Specifies if user can be prompted for credentials or not.
Supports Auto, Always, or Never. Defaults to Auto.
git config --global credential.microsoft.visualstudio.com.interactive neverSee GCM_INTERACTIVE
Forces authentication to use a modal dialog instead of asking for credentials at the command prompt.
Supports true or false. Defaults to true.
git config --global credential.modalPrompt trueSee GCM_MODAL_PROMPT
Sets the namespace for stored credentials.
By default the GCM uses the ‘git’ namespace for all stored credentials, setting this configuration value allows for control of the namespace used globally, or per host.
Supports any ASCII, alpha-numeric only value. Defaults to git.
git config --global credential.namespace nameSee GCM_NAMESPACE
Prevents the deletion of credentials even when they are reported as invalid by Git. Can lead to lockout situations once credentials expire and until those credentials are manually removed.
Supports true or false. Defaults to false.
git config --global credential.visualstudio.com.preserve trueSee GCM_PRESERVE
Sets the maximum time, in milliseconds, for a network request to wait before timing out. This allows changing the default for slow connections.
Supports an integer value. Defaults to 90,000 milliseconds.
git config --global credential.visualstudio.com.httpTimeout 100000See GCM_HTTP_TIMEOUT
Sets a duration, in hours, limit for the validity of Personal Access Tokens requested from Azure DevOps.
If the value is greater than the maximum duration set for the account, the account value supersedes. The value cannot be less than a one hour (1).
Defaults to the account token duration. Honored when authority is set to AAD or MSA.
git config --global credential.visualstudio.com.tokenDuration 24Instructs Git to supply the path portion of the remote URL to credential helpers. When path is supplied, the GCM will use the host-name + path as the key when reading and/or writing credentials.
Note: This option changes the behavior of Git.
Supports true or false. Defaults to false.
git config --global credential.bitbucket.com.useHttpPath trueInstructs Git to provide user-info to credential helpers. When user-info is supplied, the GCM will use the user-info + host-name as the key when reading and/or writing credentials. See RFC: URI Syntax, User Information for more details.
Note: This option changes the behavior of Git.
Supports any URI legal user-info. Defaults to not providing user-info.
git config --global credential.microsoft.visualstudio.com.username johndoeCauses validation of credentials before supplying them to Git. Invalid credentials get a refresh attempt before failing. Incurs minor network operation overhead.
Supports true or false. Defaults to true. Ignored when authority is set to Basic.
git config --global credential.microsoft.visualstudio.com.validate falseSee GCM_VALIDATE
Overrides GCM default scope request when generating a Personal Access Token from Azure DevOps. The supported format is one or more scope values separated by whitespace, commas, semi-colons, or pipe '|' characters.
Defaults to vso.code_write|vso.packaging; Honored when host is ‘dev.azure.com’.
git config --global credential.microsoft.visualstudio.com.vstsScope vso.code_write|vso.packaging_write|vso.test_writeSee GCM_VSTS_SCOPE
Enables trace logging of all activities. Logs are written to the local .git/ folder at the root of the repository.
Note: This setting will not override the GCM_TRACE environment variable.
Supports true or false. Defaults to false.
git config --global credential.writeLog trueSee GCM_WRITELOG
[credential "microsoft.visualstudio.com"]
authority = AAD
interactive = never
preserve = true
tokenDuration = 24
validate = false
[credential "visualstudio.com"]
authority = MSA
[credential]
helper = manager
writelog = trueIf you have an issue using GCM or Askpass, please review the following FAQ and check our issue history or our Twitter feed before opening up an item on our issues page on GitHub.
Most likely, your environment is not configured correctly. You can verify that your 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 Git Credential Manager.
git config --global credential.modalprompt true.cd to your repo and in that repo run git config credential.modalprompt true.The Git Credential Manager supports caching of SSH key password through git-askpass. Unfortunately, OpenSSH will only interact with an askpass helper if there no TTY detected (no console available). This mean, in general and for the vast majority of users, the GCM does not help with SSH passwords or certificates.
Fortunately, the Posh-Git support automatic startup of ‘ssh-agent.exe’ which does assist with SSH certificate password caching.
Yes there is: https://www.nuget.org/packages/Microsoft.Alm.Authentication. It supports the core authentication library and the VSTS specific components. If you’re looking to extend the GCM, or need a way to authenticate with VSTS but cannot leverage the GCM directly, then it is likely what you’re after.
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 Azure DevOps 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 handled by Microsoft Git Credential Manager for Mac and Linux.
The Credential Manager deployment helpers (install.cmd and GCMW-{version}.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 easier 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.
gcm-<version>.zip to your Git’s /bin folder. This varies per distribution, but it is likely next to other git tools like git-status.exe.git config --global credential.helper manager.Team Foundation Server, when deployed on a corporate Active Directory, uses the Microsoft Kerberos protocol for authentication. Git hasn’t traditionally be able to “speak” the Kerberos protocol. However, starting with v1.14.0 Git for Windows supports Microsoft Secure Channel. To enable Secure Channel support run git config --global http.sslBackend=schannel or selecting the ‘Native Windows Secure Channel library’ option during installation of Git for Windows. Secure Channel provides better integration with Windows’ networking and certificate management; enabling easier use of proxies and alternate authentication mechanisms previously unavailable to Git for Windows users.
Git needs to be convinced to “forward” credentials by supplying a blank credential set (username and password). The GCM will attempt to detect the Team Foundation Server via the HTTP headers returned when an unauthenticated request is handled by the server. If the server is configured to allow NTLM as a supported authentication protocol, the GCM will detect the setting and instruct Git to use NTLM instead of basic authentication.
Alternatively, you can configure the GCM to assume a host supports NTLM without checking. To do so, update your Git configuration by running git config --global credential.{my-tfs}.authority NTLM, where {my-tfs} can be replaced by the host name of your TFS server; the port number is not required for GCM configuration but you will want it for the Git remote.
Note: Previous versions of the GCM suggested using git credential.{url}.integrated true; while this configuration option continues to work, it has been deprecated in favor of specifying the correct authority.
Once updated, the new configuration tells the GCM to only negotiate via NTLM with the host and forward Windows credentials. Most likely, this is not what you want. Therefore, it strongly suggested that you restrict the configuration setting to the URL of your TFS Git host.
You need to configure SourceTree to use the version of Git installed for the entire system. By default, SourceTree uses a local copy of portable Git.
To fix this go to ‘Tools > Options > Git’ and click the ‘Use System Git’ button. This works in v1.8.3.0 of SourceTree.
Check that you are using the HTTP(S) URL instead of the SSH URL for your repository. You can do this by running git remote show origin. The Fetch URL and Push URL should start with https:// or http://. If this is not the case, look for the HTTP(S) URL in the web interface of Azure DevOps, TFS, GitHub or Bitbucket, and then run git remote set-url origin <url>, where <url> is the HTTP(S) URL.
When the tenant backing the Azure DevOps account changes like when you Connect VSTS account to Azure Active Directory (Azure AD), the tenant cache needs to be cleared if you’re using a GCM version prior to v1.15.0. Clearing the tenant cache is as easy as deleting the %LocalAppData%.cache file on each machine returning a login error like below. The GCM will automatically recreate and populate the cache file as needed on subsequent login attempts.
Example:
Error: cannot spawn askpass: No such file or directory
Error encountered while pushing to the remote repository: Git failed with a fatal error.
could not read Username for ‘https://******.********.***’: terminal prompts disabledWhen you have git config http.proxy or HTTPS_PROXY configured to use ServicePointManager proxy, and the URL doesn’t begin with http:// the GCM will be unable to negotiate with the proxy. This is due the way the .NET Framework WebProxy and ServicePointManager interact. You can read “ServicePointManager does not support proxies of https scheme” for additional information about this issue.
The work around is to use a proxy URL which starts with http://, or discontinue use of ServicePointManager.
Build agents, and other automation, often require specialized setup and configuration. While there is detailed documentation on GCM configuration options, below are common recommendations for settings agents often require to operate.
Note: SSH is often a better choice for automated system because requiring interactivity is a non-default option, and SSH is known to be secure and reliable.
The majority of build definitions will work with a single repository, or at least a set of repositories which all have the same authentication requirements. In this case, it is generally better to rely on Azure DevOps Build Variables; specifically the $(System.AccessToken) build process OAuth token. To enable scripts to use the build process OAuth token, go to the Options tab of the build definition and select Allow Scripts to Access OAuth Token. For more information, read Azure DevOps: Use the OAuth token to access the REST API.
Build agents cannot manage modal dialogs, therefore we recommended the following configuration.
git config --global credential.interactive neverBuild agents often need to minimize the amount of network traffic they generate.
To avoid Microsoft Account vs. Azure Active Directory look-up against an Azure DevOps account use…
… for Azure Directory backed authentication:
git config --global credential.authority Azure… for Microsoft Account backed authentication:
git config --global credential.authority Microsoft… to restrict the lifetime of VSTS personal access tokens:
git config --global credential.tokenDuration 1If your agents rely on an on premise instance of Team Foundation Server and Windows Domain Authentication, use:
git config --global credential.authority NTLMTo avoid unnecessary service account credential validation, when relying on Microsoft Account or Azure Active Directory use:
git config --global credential.validate falseDeveloping for GCM and/or Askpass requires Visual Studio 2017 or newer, any version (including the free Community Edition).
The easiest way to get started is to:
Once the GCM starts you’ll be presented with an unsatisfying console window. This is because the GCM expects to be launched by Git, not directly. However, it is easy to play the role of Git. The GCM expects Git to supply at least two pieces of information: the protocol being use and the host name for which the current operation is happening.
An example of faking Git request for GitHub credentials:
Notice the blank last line. That empty line is how Git and the GCM notify the other side that they’re done sending data. Until an empty line is sent to the GCM, it’ll keep attempting to read from standard input.
Once the blank line is fed to the GCM it’ll “do its thing”. Ideally, you can watch it work, so that you can learn how it works and then improve it. To do so, place a break point in the Main method of the ‘Program.cs’ file. Doing so will allow you to “break in” when the execution pointer reaches your break point. You’ll notice that the GCM doesn’t read from standard input immediately; instead it does some setup work to determine what it expected of it and then only reads from standard input if it is expected to.
In the case of “git credential-manager get”, the Main method will call the Program.Get method, which in turn will allocate a new OperationArguments object and initialize it with the process’ standard input pipe. This is when standard input will be consumed by the GCM.
Program.LoadOperationArguments method is where the GCM scans, parses, and consumes environmental and configuration setting values.Program.QueryCredentials method is where the “action” happens.OperationArguments class is where the GCM consumes standard input and keeps internal state.Changes to the installer (GCMW-{version}.exe) requires Inno Setup Compiler 5.5.9 or later to compile. Additionally, the IDP plugin for Inno Setup is also required.
The setup compiler pulls content from the “Deploy/” folder, therefore a completed Debug or Release build needs to have been completed prior to running the setup compiler. Content in the “Deploy/” folder will be used in the setup compilation.
The Microsoft.Alm.Authentication NuGet package is automatically created when the Microsoft.Alm.Authentication project is built. The generated “.nupkg” files can be found in the “Debug/” or “Release/” (depending on your build target) under “Microsoft.Alm.Authentication/bin/”. Both the binary and symbol packages are automatically created.
Updates to the NuGet package stream are reserved for officially built binaries.
Only Microsoft can sign binaries with the Microsoft certificate. Therefore, while anyone can build and use their own binaries from the GCM source code, only officially releases binaries will be signed by Microsoft.
The documentation is formatted using markdown and generated using Pandoc.
To enable logging, use the following:
git config --global credential.writelog trueLog files will be written to the repository’s local .git/ folder.
Additionally, the GCM outputs GIT_TRACE compatible logging. To use the GIT_TRACE mechanism you can either:
SET GCM_TRACE=1; this will cause the GCM to log directly to the console.SET GIT_TRACE=1; now Git will log directly to the console.Or
setx GCM_TRACE %UserProfile%\git.log; this will cause the GCM to log to a file located at “%UserProfile%.log”.setx GIT_TRACE %UserProfile%\git.log; now Git will log to the file located at “%UserProfile%.log”.setx GCM_TRACE "" or GIT_TRACE "".Note: The path for logging is arbitrary and both GCM and Git will create/append the file, however neither Git nor the GCM will create any folders; therefore it is up to the user to specify a folder that exists. Additionally, if the specified path contains spaces, be sure to wrap the path in double-quote characters (example: “%UserProfile%git.log”). Finally, inaccessible paths could cause either Git or the GCM to fail unexpectedly, therefor avoid specifying paths which the user’s account does not have access to; for example paths like “%ProgramFiles%.log” are not recommended because only elevated processes can write to “%ProgramFiles%”.
Debug build of the GCM will perform extended logging to the console, which is convenient for debugging purposes bug too noisy for day-to-day usage.
There are many ways to contribute.
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.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project uses the MIT License.