Skip to content

Latest commit

 

History

History
455 lines (285 loc) · 11 KB

environment.md

File metadata and controls

455 lines (285 loc) · 11 KB
Raw

Environment variables

Git Credential Manager Core work out of the box for most users. Configuration options are available to customize or tweak behavior.

Git Credential Manager Core (GCM Core) can be configured using environment variables. Environment variables take precedence over configuration options.

For the complete list of environment variables GCM Core 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 tracing disabled.

No configuration equivalent.

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.

No configuration equivalent.

GCM_TRACE_MSAUTH

Enables inclusion of Microsoft Authentication libraries (ADAL, 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 ADAL/MSAL logs.

Defaults to disabled.

No configuration equivalent.

GCM_DEBUG

Pauses execution of GCM Core 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.

No configuration equivalent.

GCM_INTERACTIVE

Permit or disable GCM Core 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 Core 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]
azure-repos Azure Repos
github GitHub
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.

Click here 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)
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_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.

Click here for more information.

Configure GCM Core 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_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 OAuth-based authentication
basic Basic/PAT-based authentication
Windows
SET GCM_GITHUB_AUTHMODES="oauth,basic"
macOS/Linux
export GCM_GITHUB_AUTHMODES="oauth,basic"

Also see: credential.gitHubAuthModes

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 is unset.

Note: This setting is only supported on Linux platforms. Setting this value on Windows and macOS has no effect. See more information about configuring secret stores on Linux here.

Value Credential Store
(unset) (error)
secretservice freedesktop.org Secret Service API via libsecret (requires a graphical interface to unlock secret collections).
gpg Use GPG to store encrypted files that are compatible with the pass utility (requires GPG and pass to initialize the store).
cache Git's built-in credential cache.
plaintext Store credentials in plaintext files (UNSECURE). Customize the plaintext store location with GCM_PLAINTEXT_STORE_PATH.
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.

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.

Linux

export GCM_PLAINTEXT_STORE_PATH=/mnt/external-drive/credentials

Also see: credential.plaintextStorePath

GCM_MSAUTH_FLOW

Specify which authentication flow should be used when performing Microsoft authentication and an interactive flow is required.

Defaults to the value auto.

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_AZREPOS_CREDENTIALTYPE (experimental)

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.

Windows
SET GCM_AZREPOS_CREDENTIALTYPE="oauth"
macOS/Linux
export GCM_AZREPOS_CREDENTIALTYPE="oauth"

Also see: credential.azreposCredentialType