Skip to content

Latest commit

 

History

History
1217 lines (810 loc) · 31.8 KB

environment.md

File metadata and controls

1217 lines (810 loc) · 31.8 KB
Raw

Environment variables

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.

Available settings

GCM_TRACE

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.

Example

Windows
SET GIT_TRACE=%UserProfile%\git.log
SET GCM_TRACE=%UserProfile%\git.log
macOS/Linux
export GIT_TRACE=$HOME/git.log
export GCM_TRACE=$HOME/git.log

If 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 disabled.

Also see: credential.trace

GCM_TRACE_SECRETS

Enables tracing of secret and sensitive information, which is by default masked in trace output. Requires that GCM_TRACE is also enabled.

Example

Windows
SET GCM_TRACE=%UserProfile%\gcm.log
SET GCM_TRACE_SECRETS=1
macOS/Linux
export GCM_TRACE=$HOME/gcm.log
export GCM_TRACE_SECRETS=1

If the value of GCM_TRACE_SECRETS is true or 1, trace logs will include secret information.

Defaults to disabled.

Also see: credential.traceSecrets

GCM_TRACE_MSAUTH

Enables inclusion of Microsoft Authentication library (MSAL) logs in GCM trace output. Requires that GCM_TRACE is also enabled.

Example

Windows
SET GCM_TRACE=%UserProfile%\gcm.log
SET GCM_TRACE_MSAUTH=1
macOS/Linux
export GCM_TRACE=$HOME/gcm.log
export GCM_TRACE_MSAUTH=1

If the value of GCM_TRACE_MSAUTH is true or 1, trace logs will include verbose MSAL logs.

Defaults to disabled.

Also see: credential.traceMsAuth

GCM_DEBUG

Pauses execution of GCM at launch to wait for a debugger to be attached.

Example

Windows
SET GCM_DEBUG=1
macOS/Linux
export GCM_DEBUG=1

Defaults to disabled.

Also see: credential.debug

GCM_INTERACTIVE

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.

Compatibility

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)

Example

Windows
SET GCM_INTERACTIVE=0
macOS/Linux
export GCM_INTERACTIVE=0

Defaults to enabled.

Also see: credential.interactive

GCM_PROVIDER

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.

Example

Windows
SET GCM_PROVIDER=github
macOS/Linux
export GCM_PROVIDER=github

Also see: credential.provider

GCM_AUTHORITY (deprecated)

This setting is deprecated and should be replaced by GCM_PROVIDER with 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)

Example

Windows
SET GCM_AUTHORITY=github
macOS/Linux
export GCM_AUTHORITY=github

Also see: credential.authority

GCM_GUI_PROMPT

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.

Example

Windows
SET GCM_GUI_PROMPT=0
macOS/Linux
export GCM_GUI_PROMPT=0

Defaults to enabled.

Also see: credential.guiPrompt

GCM_GUI_SOFTWARE_RENDERING

Force the use of software rendering for GUI prompts.

This is currently only applicable on Windows.

Example

Windows
SET GCM_GUI_SOFTWARE_RENDERING=1
macOS/Linux
export GCM_GUI_SOFTWARE_RENDERING=1

Defaults to false (use hardware acceleration where available).

Note

Windows on ARM devices defaults to using software rendering to work around a known Avalonia issue: AvaloniaUI/Avalonia#10405

Also see: credential.guiSoftwareRendering

GCM_AUTODETECT_TIMEOUT

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).

Example

Windows
SET GCM_AUTODETECT_TIMEOUT=-1
macOS/Linux
export GCM_AUTODETECT_TIMEOUT=-1

Also see: credential.autoDetectTimeout

GCM_ALLOW_WINDOWSAUTH

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

Example

Windows
SET GCM_ALLOW_WINDOWSAUTH=0
macOS/Linux
export GCM_ALLOW_WINDOWSAUTH=0

Also see: credential.allowWindowsAuth

GCM_HTTP_PROXY (deprecated)

This setting is deprecated and should be replaced by the standard http.proxy Git 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.

Windows

SET GCM_HTTP_PROXY=http://john.doe:[email protected]

macOS/Linux

export GCM_HTTP_PROXY=http://john.doe:[email protected]

Also see: credential.httpProxy

GCM_BITBUCKET_AUTHMODES

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

Windows

SET GCM_BITBUCKET_AUTHMODES="oauth,basic"

macOS/Linux

export GCM_BITBUCKET_AUTHMODES="oauth,basic"

Also see: credential.bitbucketAuthModes

GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS

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

Windows

SET GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1

macOS/Linux

export GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1

Defaults to false/disabled.

Also see: credential.bitbucketAlwaysRefreshCredentials

GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS

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

Windows

SET GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS=1

macOS/Linux

export GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS=1

Defaults to true/enabled.

Also see: credential.bitbucketValidateStoredCredentials

GCM_BITBUCKET_DATACENTER_CLIENTID

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.

Windows

SET GCM_BITBUCKET_DATACENTER_CLIENTID=1111111111111111111

macOS/Linux

export GCM_BITBUCKET_DATACENTER_CLIENTID=1111111111111111111

Defaults to undefined.

Also see: credential.bitbucketDataCenterOAuthClientId

GCM_BITBUCKET_DATACENTER_CLIENTSECRET

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.

Windows

SET GCM_BITBUCKET_DATACENTER_CLIENTSECRET=222222222222222222222

macOS/Linux

export GCM_BITBUCKET_DATACENTER_CLIENTSECRET=222222222222222222222

Defaults to undefined.

Also see: credential.bitbucketDataCenterOAuthClientSecret

GCM_GITHUB_ACCOUNTFILTERING

Enable or disable automatic account filtering for GitHub based on server hints when there are multiple available accounts. This setting is only applicable to GitHub.com with Enterprise Managed Users.

Value Description
true (default) Filter available accounts based on server hints.
false Show all available accounts.

Windows

SET GCM_GITHUB_ACCOUNTFILTERING=false

macOS/Linux

export GCM_GITHUB_ACCOUNTFILTERING=false

Also see: credential.gitHubAccountFiltering

GCM_GITHUB_AUTHMODES

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

Windows

SET GCM_GITHUB_AUTHMODES="oauth,basic"

macOS/Linux

export GCM_GITHUB_AUTHMODES="oauth,basic"

Also see: credential.gitHubAuthModes

GCM_GITLAB_AUTHMODES

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

Windows

SET GCM_GITLAB_AUTHMODES="browser"

macOS/Linux

export GCM_GITLAB_AUTHMODES="browser"

Also see: credential.gitLabAuthModes

GCM_NAMESPACE

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.

Windows

SET GCM_NAMESPACE="my-namespace"

macOS/Linux

export GCM_NAMESPACE="my-namespace"

Also see: credential.namespace

GCM_CREDENTIAL_STORE

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

Windows

SET GCM_CREDENTIAL_STORE="gpg"

macOS/Linux

export GCM_CREDENTIAL_STORE="gpg"

Also see: credential.credentialStore

GCM_CREDENTIAL_CACHE_OPTIONS

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.

Windows

SET GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300"

macOS/Linux

export GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300"

Also see: credential.cacheOptions

GCM_PLAINTEXT_STORE_PATH

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.

Windows

SETX GCM_PLAINTEXT_STORE_PATH=D:\credentials

macOS/Linux

export GCM_PLAINTEXT_STORE_PATH=/mnt/external-drive/credentials

Also see: credential.plaintextStorePath

GCM_DPAPI_STORE_PATH

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.

Windows

SETX GCM_DPAPI_STORE_PATH=D:\credentials

Also see: credential.dpapiStorePath

GCM_GPG_PATH

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.

macOS/Linux

export GCM_GPG_PATH="/usr/local/bin/gpg2"

No configuration equivalent.

GCM_MSAUTH_FLOW

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.

Windows

SET GCM_MSAUTH_FLOW="devicecode"

macOS/Linux

export GCM_MSAUTH_FLOW="devicecode"

Also see: credential.msauthFlow

GCM_MSAUTH_USEBROKER (experimental)

Use the operating system account manager where available.

Defaults to false. In certain cloud hosted environments when using a work or school account, such as Microsoft DevBox, the default is true.

These defaults are 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.

Windows

SET GCM_MSAUTH_USEBROKER="true"

macOS/Linux

export GCM_MSAUTH_USEBROKER="false"

Also see: credential.msauthUseBroker

GCM_MSAUTH_USEDEFAULTACCOUNT (experimental)

Use the current operating system account by default when the broker is enabled.

Defaults to false. In certain cloud hosted environments when using a work or school account, such as Microsoft DevBox, the default is true.

These defaults are subject to change in the future.

Value Description
true Use the current operating system account by default.
false (default) Do not assume any account to use by default.

Windows

SET GCM_MSAUTH_USEDEFAULTACCOUNT="true"

macOS/Linux

export GCM_MSAUTH_USEDEFAULTACCOUNT="false"

Also see: credential.msauthUseDefaultAccount

GCM_AZREPOS_CREDENTIALTYPE

Specify the type of credential the Azure Repos host provider should return.

Defaults to the value pat. In certain cloud hosted environments when using a work or school account, such as Microsoft DevBox, the default value is oauth.

Value Description
pat Azure DevOps personal access tokens
oauth Microsoft identity OAuth tokens (AAD or MSA tokens)

More information about Azure Access tokens can be found here.

Windows

SET GCM_AZREPOS_CREDENTIALTYPE="oauth"

macOS/Linux

export GCM_AZREPOS_CREDENTIALTYPE="oauth"

Also see: credential.azreposCredentialType

GCM_AZREPOS_MANAGEDIDENTITY

Use a Managed Identity to authenticate with Azure Repos.

The value system will tell GCM to use the system-assigned Managed Identity.

To specify a user-assigned Managed Identity, use the format id://{clientId} where {clientId} is the client ID of the Managed Identity. Alternatively any GUID-like value will also be interpreted as a user-assigned Managed Identity client ID.

To specify a Managed Identity associated with an Azure resource, you can use the format resource://{resourceId} where {resourceId} is the ID of the resource.

For more information about managed identities, see the Azure DevOps documentation.

Value Description
system System-Assigned Managed Identity
[guid] User-Assigned Managed Identity with the specified client ID
id://[guid] User-Assigned Managed Identity with the specified client ID
resource://[guid] User-Assigned Managed Identity for the associated resource

Windows

SET GCM_AZREPOS_MANAGEDIDENTITY="id://11111111-1111-1111-1111-111111111111"

macOS/Linux

export GCM_AZREPOS_MANAGEDIDENTITY="id://11111111-1111-1111-1111-111111111111"

Also see: credential.azreposManagedIdentity

GCM_AZREPOS_SERVICE_PRINCIPAL

Specify the client and tenant IDs of a service principal to use when performing Microsoft authentication for Azure Repos.

The value of this setting should be in the format: {tenantId}/{clientId}.

You must also set at least one authentication mechanism if you set this value:

For more information about service principals, see the Azure DevOps documentation.

Windows

SET GCM_AZREPOS_SERVICE_PRINCIPAL="11111111-1111-1111-1111-111111111111/22222222-2222-2222-2222-222222222222"

macOS/Linux

export GCM_AZREPOS_SERVICE_PRINCIPAL="11111111-1111-1111-1111-111111111111/22222222-2222-2222-2222-222222222222"

Also see: credential.azreposServicePrincipal

GCM_AZREPOS_SP_SECRET

Specifies the client secret for the service principal when performing Microsoft authentication for Azure Repos with GCM_AZREPOS_SERVICE_PRINCIPAL set.

Windows

SET GCM_AZREPOS_SP_SECRET="da39a3ee5e6b4b0d3255bfef95601890afd80709"

macOS/Linux

export GCM_AZREPOS_SP_SECRET="da39a3ee5e6b4b0d3255bfef95601890afd80709"

Also see: credential.azreposServicePrincipalSecret

GCM_AZREPOS_SP_CERT_THUMBPRINT

Specifies the thumbprint of a certificate to use when authenticating as a service principal for Azure Repos when GCM_AZREPOS_SERVICE_PRINCIPAL is set.

Windows

SET GCM_AZREPOS_SP_CERT_THUMBPRINT="9b6555292e4ea21cbc2ebd23e66e2f91ebbe92dc"

macOS/Linux

export GCM_AZREPOS_SP_CERT_THUMBPRINT="9b6555292e4ea21cbc2ebd23e66e2f91ebbe92dc"

Also see: credential.azreposServicePrincipalCertificateThumbprint

GCM_AZREPOS_SP_CERT_SEND_X5C

When using a certificate for service principal authentication, this configuration specifies whether the X5C claim should be should be sent to the STS. Sending the x5c enables application developers to achieve easy certificate rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request, so that Azure AD can use it to validate the subject name based on a trusted issuer policy. This saves the application admin from the need to explicitly manage the certificate rollover. For details see https://aka.ms/msal-net-sni.

Windows

SET GCM_AZREPOS_SP_CERT_SEND_X5C="true"

macOS/Linux

export GCM_AZREPOS_SP_CERT_SEND_X5C="true"

Also see: credential.azreposServicePrincipalCertificateSendX5C

GIT_TRACE2

Turns on Trace2 Normal Format tracing - see Git's Trace2 Normal Format documentation for more details.

Windows

SET GIT_TRACE2=%UserProfile%\log.normal

macOS/Linux

export GIT_TRACE2=~/log.normal

If the value of GIT_TRACE2 is a full path to a file in an existing directory, logs are appended to the file.

If the value of GIT_TRACE2 is true or 1, logs are written to standard error.

Defaults to disabled.

Also see: trace2.normalFormat

GIT_TRACE2_EVENT

Turns on Trace2 Event Format tracing - see Git's Trace2 Event Format documentation for more details.

Windows

SET GIT_TRACE2_EVENT=%UserProfile%\log.event

macOS/Linux

export GIT_TRACE2_EVENT=~/log.event

If the value of GIT_TRACE2_EVENT is a full path to a file in an existing directory, logs are appended to the file.

If the value of GIT_TRACE2_EVENT is true or 1, logs are written to standard error.

Defaults to disabled.

Also see: trace2.eventFormat

GIT_TRACE2_PERF

Turns on Trace2 Performance Format tracing - see Git's Trace2 Performance Format documentation for more details.

Windows

SET GIT_TRACE2_PERF=%UserProfile%\log.perf

macOS/Linux

export GIT_TRACE2_PERF=~/log.perf

If the value of GIT_TRACE2_PERF is a full path to a file in an existing directory, logs are appended to the file.

If the value of GIT_TRACE2_PERF is true or 1, logs are written to standard error.

Defaults to disabled.

Also see: trace2.perfFormat