Git Credential Manager works out of the box for most users. Configuration options are available to customize or tweak behavior.
Git Credential Manager (GCM) can be configured using environment variables. Environment variables take precedence over configuration options and enterprise system administrator default values.
For the complete list of environment variables GCM understands, see the list below.
Enables trace logging of all activities.
Configuring Git and GCM to trace to the same location is often desirable, and
GCM is compatible and cooperative with GIT_TRACE.
SET GIT_TRACE=%UserProfile%\git.log
SET GCM_TRACE=%UserProfile%\git.logexport GIT_TRACE=$HOME/git.log
export GCM_TRACE=$HOME/git.logIf the value of GCM_TRACE is a full path to a file in an existing directory,
logs are appended to the file.
If the value of GCM_TRACE is true or 1, logs are written to standard error.
Defaults to tracing disabled.
No configuration equivalent.
Enables tracing of secret and sensitive information, which is by default masked
in trace output. Requires that GCM_TRACE is also enabled.
SET GCM_TRACE=%UserProfile%\gcm.log
SET GCM_TRACE_SECRETS=1export GCM_TRACE=$HOME/gcm.log
export GCM_TRACE_SECRETS=1If the value of GCM_TRACE_SECRETS is true or 1, trace logs will include
secret information.
Defaults to disabled.
No configuration equivalent.
Enables inclusion of Microsoft Authentication libraries (ADAL, MSAL) logs in GCM
trace output. Requires that GCM_TRACE is also enabled.
SET GCM_TRACE=%UserProfile%\gcm.log
SET GCM_TRACE_MSAUTH=1export GCM_TRACE=$HOME/gcm.log
export GCM_TRACE_MSAUTH=1If the value of GCM_TRACE_MSAUTH is true or 1, trace logs will include
verbose ADAL/MSAL logs.
Defaults to disabled.
No configuration equivalent.
Pauses execution of GCM at launch to wait for a debugger to be attached.
SET GCM_DEBUG=1export GCM_DEBUG=1Defaults to disabled.
No configuration equivalent.
Permit or disable GCM from interacting with the user (showing GUI or TTY prompts). If interaction is required but has been disabled, an error is returned.
This can be helpful when using GCM in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinitely waiting for a non-existent user.
To disable interactivity set this to false or 0.
In previous versions of GCM this setting had a different behavior and accepted
other values. The following table summarizes the change in behavior and the
mapping of older values such as never:
| Value(s) | Old meaning | New meaning |
|---|---|---|
auto |
Prompt if required – use cached credentials if possible | (unchanged) |
never, false |
Never prompt – fail if interaction is required | (unchanged) |
always, force, true |
Always prompt – don't use cached credentials | Prompt if required (same as the old auto value) |
SET GCM_INTERACTIVE=0export GCM_INTERACTIVE=0Defaults to enabled.
Also see: credential.interactive
Define the host provider to use when authenticating.
| ID | Provider |
|---|---|
auto (default) |
[automatic] (learn more) |
azure-repos |
Azure Repos |
github |
GitHub |
gitlab |
GitLab (supports OAuth in browser, personal access token and Basic Authentication) |
generic |
Generic (any other provider not listed above) |
Automatic provider selection is based on the remote URL.
This setting is typically used with a scoped URL to map a particular set of remote URLs to providers, for example to mark a host as a GitHub Enterprise instance.
SET GCM_PROVIDER=githubexport GCM_PROVIDER=githubAlso see: credential.provider
This setting is deprecated and should be replaced by
GCM_PROVIDERwith the corresponding provider ID value.See the migration guide for more information.
Select the host provider to use when authenticating by which authority is supported by the providers.
| Authority | Provider(s) |
|---|---|
auto (default) |
[automatic] |
msa, microsoft, microsoftaccount, aad, azure, azuredirectory, live, liveconnect, liveid |
Azure Repos (supports Microsoft Authentication) |
github |
GitHub (supports GitHub Authentication) |
gitlab |
GitLab (supports OAuth in browser, personal access token and Basic Authentication) |
basic, integrated, windows, kerberos, ntlm, tfs, sso |
Generic (supports Basic and Windows Integrated Authentication) |
SET GCM_AUTHORITY=githubexport GCM_AUTHORITY=githubAlso see: credential.authority
Permit or disable GCM from presenting GUI prompts. If an equivalent terminal/ text-based prompt is available, that will be shown instead.
To disable all interactivity see GCM_INTERACTIVE.
SET GCM_GUI_PROMPT=0export GCM_GUI_PROMPT=0Defaults to enabled.
Also see: credential.guiPrompt
Set the maximum length of time, in milliseconds, that GCM should wait for a network response during host provider auto-detection probing.
See autodetection for more information.
Note: Use a negative or zero value to disable probing altogether.
Defaults to 2000 milliseconds (2 seconds).
SET GCM_AUTODETECT_TIMEOUT=-1export GCM_AUTODETECT_TIMEOUT=-1Also see: credential.autoDetectTimeout
Allow detection of Windows Integrated Authentication (WIA) support for generic
host providers. Setting this value to false will prevent the use of WIA and
force a basic authentication prompt when using the Generic host provider.
Note: WIA is only supported on Windows.
Note: WIA is an umbrella term for NTLM and Kerberos (and Negotiate).
| Value | WIA detection |
|---|---|
true, 1, yes, on (default) |
Permitted |
false, 0, no, off |
Not permitted |
SET GCM_ALLOW_WINDOWSAUTH=0export GCM_ALLOW_WINDOWSAUTH=0Also see: credential.allowWindowsAuth
This setting is deprecated and should be replaced by the standard
http.proxyGit configuration option.See the HTTP proxy configuration for more information.
Configure GCM to use the a proxy for network operations.
Note: Git itself does not respect this setting; this affects GCM only.
SET GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.comexport GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.comAlso see: credential.httpProxy
Override the available authentication modes presented during Bitbucket authentication. If this option is not set, then the available authentication modes will be automatically detected.
Note: This setting only applies to Bitbucket.org, and not Server or DC instances.
Note: This setting supports multiple values separated by commas.
| Value | Authentication Mode |
|---|---|
| (unset) | Automatically detect modes |
oauth |
OAuth-based authentication |
basic |
Basic/PAT-based authentication |
SET GCM_BITBUCKET_AUTHMODES="oauth,basic"export GCM_BITBUCKET_AUTHMODES="oauth,basic"Also see: credential.bitbucketAuthModes
Forces GCM to ignore any existing stored Basic Auth or OAuth access tokens and always run through the process to refresh the credentials before returning them to Git.
This is especially relevant to OAuth credentials. Bitbucket.org access tokens expire after 2 hours, after that the refresh token must be used to get a new access token.
Enabling this option will improve performance when using Oauth2 and interacting with Bitbucket.org if, on average, commits are done less frequently than every 2 hours.
Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials every time.
| Value | Refresh Credentials Before Returning |
|---|---|
true, 1, yes, on |
Always |
false, 0, no, off(default) |
Only when the credentials are found to be invalid |
SET GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1export GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1Defaults to false/disabled.
Also see: credential.bitbucketAlwaysRefreshCredentials
Forces GCM to validate any stored credentials before returning them to Git. It does this by calling a REST API resource that requires authentication.
Disabling this option reduces the HTTP traffic within GCM when it is retrieving credentials. This may improve user performance, but will increase the number of times Git remote calls fail to authenticate with the host and therefore require the user to re-try the Git remote call.
Enabling this option helps ensure Git is always provided with valid credentials.
| Value | Validate credentials |
|---|---|
true, 1, yes, on(default) |
Always |
false, 0, no, off |
Never |
SET GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS=1export GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS=1Defaults to true/enabled.
Also see: credential.bitbucketValidateStoredCredentials
To use OAuth with Bitbucket DC it is necessary to create an external, incoming AppLink.
It is then necessary to configure the local GCM installation with the OAuth ClientId and ClientSecret from the AppLink.
SET GCM_BITBUCKET_DATACENTER_CLIENTID=1111111111111111111export GCM_BITBUCKET_DATACENTER_CLIENTID=1111111111111111111Defaults to undefined.
Also see: credential.bitbucketDataCenterOAuthClientId
To use OAuth with Bitbucket DC it is necessary to create an external, incoming AppLink.
It is then necessary to configure the local GCM installation with the OAuth ClientId and ClientSecret from the AppLink.
SET GCM_BITBUCKET_DATACENTER_CLIENTSECRET=222222222222222222222export GCM_BITBUCKET_DATACENTER_CLIENTSECRET=222222222222222222222Defaults to undefined.
Also see: credential.bitbucketDataCenterOAuthClientSecret
Override the available authentication modes presented during GitHub authentication. If this option is not set, then the available authentication modes will be automatically detected.
Note: This setting supports multiple values separated by commas.
| Value | Authentication Mode |
|---|---|
| (unset) | Automatically detect modes |
oauth |
Expands to: browser, device |
browser |
OAuth authentication via a web browser (requires a GUI) |
device |
OAuth authentication with a device code |
basic |
Basic authentication using username and password |
pat |
Personal Access Token (pat)-based authentication |
SET GCM_GITHUB_AUTHMODES="oauth,basic"export GCM_GITHUB_AUTHMODES="oauth,basic"Also see: credential.gitHubAuthModes
Override the available authentication modes presented during GitLab authentication. If this option is not set, then the available authentication modes will be automatically detected.
Note: This setting supports multiple values separated by commas.
| Value | Authentication Mode |
|---|---|
| (unset) | Automatically detect modes |
browser |
OAuth authentication via a web browser (requires a GUI) |
basic |
Basic authentication using username and password |
pat |
Personal Access Token (pat)-based authentication |
SET GCM_GITLAB_AUTHMODES="browser"export GCM_GITLAB_AUTHMODES="browser"Also see: credential.gitLabAuthModes
Use a custom namespace prefix for credentials read and written in the OS
credential store. Credentials will be stored in the format
{namespace}:{service}.
Defaults to the value git.
SET GCM_NAMESPACE="my-namespace"export GCM_NAMESPACE="my-namespace"Also see: credential.namespace
Select the type of credential store to use on supported platforms.
Default value on Windows is wincredman, on macOS is keychain, and is unset
on Linux.
Note: For more information about configuring secret stores see the credential stores documentation.
| Value | Credential Store | Platforms |
|---|---|---|
| (unset) | Windows: wincredman, macOS: keychain, Linux: (none) |
- |
wincredman |
Windows Credential Manager (not available over SSH). | Windows |
dpapi |
DPAPI protected files. Customize the DPAPI store location with GCM_DPAPI_STORE_PATH |
Windows |
keychain |
macOS Keychain. | macOS |
secretservice |
freedesktop.org Secret Service API via libsecret (requires a graphical interface to unlock secret collections). | Linux |
gpg |
Use GPG to store encrypted files that are compatible with the pass utility (requires GPG and pass to initialize the store). |
macOS, Linux |
cache |
Git's built-in credential cache. | Windows, macOS, Linux |
plaintext |
Store credentials in plaintext files (UNSECURE). Customize the plaintext store location with GCM_PLAINTEXT_STORE_PATH. |
Windows, macOS, Linux |
SET GCM_CREDENTIAL_STORE="gpg"export GCM_CREDENTIAL_STORE="gpg"Also see: credential.credentialStore
Pass options
to the Git credential cache when GCM_CREDENTIAL_STORE
is set to cache. This allows you to select a different amount
of time to cache credentials (the default is 900 seconds) by passing
"--timeout <seconds>". Use of other options like --socket is untested
and unsupported, but there's no reason it shouldn't work.
Defaults to empty.
SET GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300"export GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300"Also see: credential.cacheOptions
Specify a custom directory to store plaintext credential files in when
GCM_CREDENTIAL_STORE is set to plaintext.
Defaults to the value ~/.gcm/store or %USERPROFILE%\.gcm\store.
SETX GCM_PLAINTEXT_STORE_PATH=D:\credentialsexport GCM_PLAINTEXT_STORE_PATH=/mnt/external-drive/credentialsAlso see: credential.plaintextStorePath
Specify a custom directory to store DPAPI protected credential files in when
GCM_CREDENTIAL_STORE is set to dpapi.
Defaults to the value %USERPROFILE%\.gcm\dpapi_store.
SETX GCM_DPAPI_STORE_PATH=D:\credentialsAlso see: credential.dpapiStorePath
Specify the path (including the executable name) to the version of gpg used
by pass (gpg2 if present, otherwise gpg). This is primarily meant to allow
manual resolution of the conflict that occurs on legacy Linux systems with
parallel installs of gpg and gpg2.
If not specified, GCM defaults to using the version of gpg2 on the $PATH,
falling back on gpg if gpg2 is not found.
export GCM_GPG_PATH="/usr/local/bin/gpg2"No configuration equivalent.
Specify which authentication flow should be used when performing Microsoft authentication and an interactive flow is required.
Defaults to auto.
Note: If GCM_MSAUTH_USEBROKER is set to true
and the operating system authentication broker is available, all flows will be
delegated to the broker. If both of those things are true, then the value of
GCM_MSAUTH_FLOW has no effect.
| Value | Authentication Flow |
|---|---|
auto (default) |
Select the best option depending on the current environment and platform. |
embedded |
Show a window with embedded web view control. |
system |
Open the user's default web browser. |
devicecode |
Show a device code. |
SET GCM_MSAUTH_FLOW="devicecode"export GCM_MSAUTH_FLOW="devicecode"Also see: credential.msauthFlow
Use the operating system account manager where available.
Defaults to false. This default is subject to change in the future.
Note: before you enable this option on Windows, please review the details about what this means to your local Windows user account.
| Value | Description |
|---|---|
true |
Use the operating system account manager as an authentication broker. |
false (default) |
Do not use the broker. |
SET GCM_MSAUTH_USEBROKER="true"export GCM_MSAUTH_USEBROKER="false"Also see: credential.msauthUseBroker
Specify the type of credential the Azure Repos host provider should return.
Defaults to the value pat.
| Value | Description |
|---|---|
pat (default) |
Azure DevOps personal access tokens |
oauth |
Microsoft identity OAuth tokens (AAD or MSA tokens) |
More information about Azure Access tokens can be found here.
SET GCM_AZREPOS_CREDENTIALTYPE="oauth"export GCM_AZREPOS_CREDENTIALTYPE="oauth"Also see: credential.azreposCredentialType