docs: Clean up and modernize the markdown used across GCM docs.
Include a .vscode/spellright dictionary for easier maintenance of documentation (specifcally related to spelling). Apply the following rules: * One sentence per line (markdown ignores single EOL) for easier change reviews. * Use headers (aka # text) consistently and correctly. * Use code (aka `text`) markup consistently and correctly. * Use single- and double-quotes consistently and correctly. * Use emphasis consistently and correctly. * Correct a lot if spelling mistakes. * Link text where is makes sense to do so. * Avoid "naked" URL text.
This commit is contained in:
J Wyman ∞
Родитель
3a85f87a87
Коммит
7688f77a33
|
|
@ -0,0 +1,9 @@
|
|||
git
|
||||
cs
|
||||
Inno
|
||||
Cli
|
||||
Alm
|
||||
Pandoc
|
||||
writelog
|
||||
vsts
|
||||
config
|
||||
|
|
@ -1,11 +1,14 @@
|
|||
# Git Askpass for Windows
|
||||
|
||||
[Git Askpass for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (Askpass) provides secure Git credential storage for Windows. Askpass provides multi-factor authentication support for [Visual Studio Team Services](https://www.visualstudio.com/), [Team Foundation Server](https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx), and [GitHub](https://github.com/).
|
||||
[Git Askpass for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (Askpass) provides secure Git credential storage for Windows.
|
||||
Askpass provides multi-factor authentication support for [Visual Studio Team Services](https://www.visualstudio.com/), [Team Foundation Server](https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx), and [GitHub](https://github.com/).
|
||||
|
||||
## Usage
|
||||
|
||||
After installation and configuration, Git will use the Git Askpass and you will only need to interact with any authentication dialogs asking for credentials. The Askpass stays invisible as much as possible, so ideally you’ll forget that you’re depending on Askpass at all.
|
||||
After installation and configuration, Git will use the Git Askpass and you will only need to interact with any authentication dialogs asking for credentials.
|
||||
The Askpass stays invisible as much as possible, so ideally you'll forget that you're depending on Askpass at all.
|
||||
|
||||
git askpass
|
||||
`git askpass`
|
||||
|
||||
For Git to use Askpass correctly, the `GIT_ASKPASS` environment variable needs contain the full path to the `git-askpass.exe` executable (example: `setx GIT_ASKPASS "C:\Program Files\Git\mingw64\libexec\git-core\git-askpass.exe"`). SSH can also be configured to use Askpass in the same manner using the `SSH_ASKPASS` environment variable; however, SSH currently will not use Askpass if it detects a TTY console (ala the ability to just ask on the console).
|
||||
For Git to use Askpass correctly, the `GIT_ASKPASS` environment variable needs contain the full path to the `git-askpass.exe` executable (example: `setx GIT_ASKPASS "C:\Program Files\Git\mingw64\libexec\git-core\git-askpass.exe"`).
|
||||
SSH can also be configured to use Askpass in the same manner using the `SSH_ASKPASS` environment variable; however, SSH currently will not use Askpass if it detects a TTY console (ala the ability to just ask on the console).
|
||||
|
|
|
|||
|
|
@ -1,8 +1,18 @@
|
|||
# Build Agents and Automation
|
||||
|
||||
Build agents, and other automation, often require specialized setup and configuration. While there is detailed documentation on [GCM configuration options](Configuration.md), below are common recommendations for settings agents often require to operate.
|
||||
Build agents, and other automation, often require specialized setup and configuration.
|
||||
While there is detailed documentation on [GCM configuration options](Configuration.md), below are common recommendations for settings agents often require to operate.
|
||||
|
||||
## Recommendations
|
||||
_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.
|
||||
|
||||
## Recommendations for VSTS Build Services
|
||||
|
||||
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 [VSTS Build Variables](https://docs.microsoft.com/en-us/vsts/build-release/concepts/definitions/build/variables?tabs=batch); 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 [VSTS: Use the OAuth token to access the REST API](https://docs.microsoft.com/en-us/vsts/build-release/actions/scripts/powershell#oauth).
|
||||
|
||||
## Recommendations for Other Build Services
|
||||
|
||||
Build agents cannot manage modal dialogs, therefore we recommended the following configuration.
|
||||
|
||||
|
|
@ -14,20 +24,20 @@ To avoid Microsoft Account vs. Azure Active Directory look-up against a Visual S
|
|||
|
||||
... for Azure Directory backed authentication:
|
||||
|
||||
`git config --global credential.authority Azure`
|
||||
git config --global credential.authority Azure
|
||||
|
||||
... for Microsoft Account backed authentication:
|
||||
|
||||
`git config --global credential.authority Microsoft`
|
||||
git config --global credential.authority Microsoft
|
||||
|
||||
... to restrict the lifetime of VSTS personal access tokens:
|
||||
|
||||
`git config --global credential.tokenDuration 1`
|
||||
git config --global credential.tokenDuration 1
|
||||
|
||||
If your agents rely on an on premise instance of Team Foundation Server and [Windows Domain Authentication](https://msdn.microsoft.com/en-us/library/ee253152(v=bts.10).aspx), use:
|
||||
|
||||
`git config --global credential.authority NTLM`
|
||||
git config --global credential.authority NTLM
|
||||
|
||||
To avoid unnecessary service account credential validation, when relying on Microsoft Account or Azure Active Directory use:
|
||||
|
||||
`git config --global credential.validate false`
|
||||
git config --global credential.validate false
|
||||
|
|
|
|||
|
|
@ -1,130 +1,162 @@
|
|||
# Bitbucket Authentication, 2FA and OAuth
|
||||
|
||||
By default for authenticating against private Git repositories Bitbucket supports SSH and username/password Basic Auth over HTTPS. Username/password Basic Auth over HTTPS is also available for REST api access. Additionally Bitbucket supports App-specific passwords which can be used via Basic Auth as username/app-pecific-password.
|
||||
By default for authenticating against private Git repositories Bitbucket supports SSH and username/password Basic Auth over HTTPS.
|
||||
Username/password Basic Auth over HTTPS is also available for REST API access.
|
||||
Additionally Bitbucket supports App-specific passwords which can be used via Basic Auth as username/app-specific-password.
|
||||
|
||||
To enhance security Bitbucket offers optional Two-Factor Authentication (2FA). When 2FA is enabled username/password Basic Auth access to the REST APIs and to Git repositories is suspended. At that point users are left with the choice of username/apps-pecific-password Basic Auth for REST APIs and Git interactions, OAuth for REST APIs and Git/Hg interactions or SSH for Git/HG interactions and one of the previous choices for REST APIs. SSH and REST API access are beyond the scope of this document. Follow this like to read about Bitbucket's 2FA implementation https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html
|
||||
To enhance security Bitbucket offers optional Two-Factor Authentication (2FA). When 2FA is enabled username/password Basic Auth access to the REST APIs and to Git repositories is suspended.
|
||||
At that point users are left with the choice of username/apps-specific-password Basic Auth for REST APIs and Git interactions, OAuth for REST APIs and Git/Hg interactions or SSH for Git/HG interactions and one of the previous choices for REST APIs.
|
||||
SSH and REST API access are beyond the scope of this document.
|
||||
Read about [Bitbucket's 2FA implementation](https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html).
|
||||
|
||||
App-specific passwords are not particularly user friendly as once created Bitbucket hides their value, even from the owner. They are intended for use within application that talk to Bitbucket where application can remember and use the app-specific-password. For further information see https://confluence.atlassian.com/display/BITBUCKET/App+passwords
|
||||
App-specific passwords are not particularly user friendly as once created Bitbucket hides their value, even from the owner.
|
||||
They are intended for use within application that talk to Bitbucket where application can remember and use the app-specific-password.
|
||||
[Additional information](https://confluence.atlassian.com/display/BITBUCKET/App+passwords).
|
||||
|
||||
OAuth is the intended authentication method for user interactions with HTTPS remote urls for Git repositories when 2FA is active. Essentially once a client application has an OAuth access token it can be used in place of a user's password. More information about Bitbucket's OAuth implementation can be found here https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html
|
||||
OAuth is the intended authentication method for user interactions with HTTPS remote URL for Git repositories when 2FA is active.
|
||||
Essentially once a client application has an OAuth access token it can be used in place of a user's password.
|
||||
Read more about information [Bitbucket's OAuth implementation](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html).
|
||||
|
||||
Bitbucket's OAuth implementation follows the standard specifications for OAuth 2.0, which is out of scope for this document. However it implements a comparatively rare part of OAuth 2.0 Refresh Tokens. Bitbucket's Access Token's expire after 1 hour if not revoked, as opposed to GitHub's that expire after 1 year. When GitHub's Access Tokens expire the user must articipate in the standard OAuth authentication flow to get a new Access Token. Since this occurs, in theory, once per year this is not too onerous. Since Bitbucket's Access Tokens expire every hour it is too much to expect a user to go through the OAuth authentication flow every hour. So Bitbcuket implements refresh Tokens. Refresh Tokens are issued to the client application at the same time as Access Tokens. They can only be used to request a new Access Token, and then only if they have not been revoked.
|
||||
Bitbucket's OAuth implementation follows the standard specifications for OAuth 2.0, which is out of scope for this document.
|
||||
However it implements a comparatively rare part of OAuth 2.0 Refresh Tokens.
|
||||
Bitbucket's Access Token's expire after 1 hour if not revoked, as opposed to GitHub's that expire after 1 year.
|
||||
When GitHub's Access Tokens expire the user must anticipate in the standard OAuth authentication flow to get a new Access Token. Since this occurs, in theory, once per year this is not too onerous.
|
||||
Since Bitbucket's Access Tokens expire every hour it is too much to expect a user to go through the OAuth authentication flow every hour.
|
||||
Bitbucket implements refresh Tokens.
|
||||
Refresh Tokens are issued to the client application at the same time as Access Tokens.
|
||||
They can only be used to request a new Access Token, and then only if they have not been revoked.
|
||||
As such the support for Bitbucket and the use of its OAuth in the Git Credentials Manager differs significantly from how VSTS and GitHub are implemented.
|
||||
This is explained in more detail below.
|
||||
|
||||
As such the support for Bitbucket and the use of its OAuth in the Git Credentials Manager differs significantly from GitHub. This is explained in more detail below.
|
||||
## Multiple User Accounts
|
||||
|
||||
# Multiple user accounts.
|
||||
|
||||
Unlike the GitHub implementation within the Git Credential Manager, the Bitbucket implementation stores 'secrets', passwords, app-specific passwords, or oauth tokens, with usernames in the Windows Credential Manager/Vault.
|
||||
|
||||
Depending on the circumstances this means either saving an explicit username in to the Windows Credential Manager/Vault or including the username in the URL used as the identifying key of entries in the Windows Credential Manager/Vault, i.e. using a key such as 'git:https://mminns@bitbucket.org/ rather than 'git:https://bitbucket.org'.
|
||||
Unlike the GitHub implementation within the Git Credential Manager, the Bitbucket implementation stores 'secrets', passwords, app-specific passwords, or OAuth tokens, with usernames in the [Windows Credential Manager](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374792(v=vs.85).aspx) vault.
|
||||
|
||||
Depending on the circumstances this means either saving an explicit username in to the Windows Credential Manager/Vault or including the username in the URL used as the identifying key of entries in the Windows Credential Manager vault, i.e. using a key such as `git:https://mminns@bitbucket.org/` rather than `git:https://bitbucket.org`.
|
||||
This means that the Bitbucket implementation in the GCM can support multiple accounts, and usernames, for a single user against Bitbucket, e.g. a personal account and a work account.
|
||||
|
||||
# Authentication User Experience.
|
||||
When the GCM is triggered by Git, the GCM will check the `host` parameter passed to it. If it contains `bitbucket.org` it will trigger the Bitbucket related processes.
|
||||
## Authentication User Experience
|
||||
|
||||
## Basic Authentication
|
||||
If the GCM needs to prompt the user for credentials they will always be shown an initial dialog where they can enter a username and password. If the `username` parameter was passed into the GCM it is used to pre-populate the username field, although it can be overriden.
|
||||
When the GCM is triggered by Git, the GCM will check the `host` parameter passed to it.
|
||||
If it contains `bitbucket.org` it will trigger the Bitbucket related processes.
|
||||
|
||||
When username and password credentials are submitted the GCM will use them to attempt to retrieve a token, for Basic Auth this token is in effect the password the user just entered. The GCM retrieves this `token` by checking the password can be used to successfully retrieve the User profile via the Bitbucket REST API.
|
||||
### Basic Authentication
|
||||
|
||||
If the username/password credentials sent as Basic Auth credentials works, then the password is identified as the token. The credentials, the username and the password/token, are then stored and the values returned to Git.
|
||||
If the GCM needs to prompt the user for credentials they will always be shown an initial dialog where they can enter a username and password. If the `username` parameter was passed into the GCM it is used to pre-populate the username field, although it can be overridden.
|
||||
When username and password credentials are submitted the GCM will use them to attempt to retrieve a token, for Basic Authentication this token is in effect the password the user just entered.
|
||||
The GCM retrieves this `token` by checking the password can be used to successfully retrieve the User profile via the Bitbucket REST API.
|
||||
|
||||
If the username and password credentials sent as Basic Authentication credentials works, then the password is identified as the token. The credentials, the username and the password/token, are then stored and the values returned to Git.
|
||||
|
||||
If the request for the User profile via the REST API fails with a 401 return code it indicates the username/password combination is invalid, nothing is stored and nothing is returned to Git.
|
||||
|
||||
However if the request fails with a 403 (Forbidden) return code, this indicates that the username and password are valid but 2FA is enabled on the Bitbucket Account. When this occurs the user it prompted to complete the OAuth authentication process.
|
||||
However if the request fails with a 403 (Forbidden) return code, this indicates that the username and password are valid but 2FA is enabled on the Bitbucket Account.
|
||||
When this occurs the user it prompted to complete the OAuth authentication process.
|
||||
|
||||
## OAuth
|
||||
Oauth authentication prompts the User with a new dialog where they can trigger OAuth authentication. This involves opening a browser request to _https://bitbucket.org/site/oauth2/authorize?response_type=code&client_id={consumerkey}&state=authenticated&scope={scopes}&redirect_uri=http://localhost:34106/_ . This will trigger a flow on Bitbucket where the user must login, potentially including a 2FA prompt, and authorize the GCM to access Bitbucket with the specified scopes. The GCM will spawn a temporary, local webserver, listening on port 34106, to handle the OAuth redirect/callback. Assuming the user successfully logins into Bitbucket and authorizes the GCM this callback will include the Access and Refresh Tokens.
|
||||
### OAuth
|
||||
|
||||
OAuth authentication prompts the User with a new dialog where they can trigger OAuth authentication.
|
||||
This involves opening a browser request to `_https://bitbucket.org/site/oauth2/authorize?response_type=code&client_id={consumerkey}&state=authenticated&scope={scopes}&redirect_uri=http://localhost:34106/_`.
|
||||
This will trigger a flow on Bitbucket where the user must login, potentially including a 2FA prompt, and authorize the GCM to access Bitbucket with the specified scopes.
|
||||
The GCM will spawn a temporary, local webserver, listening on port 34106, to handle the OAuth redirect/callback.
|
||||
Assuming the user successfully logins into Bitbucket and authorizes the GCM this callback will include the Access and Refresh Tokens.
|
||||
|
||||
The Access and Refresh Tokens will be stored against the username and the username/Access Token credentials returned to Git.
|
||||
|
||||
# GCM concepts
|
||||
## Approve
|
||||
See Store
|
||||
## GCM concepts
|
||||
|
||||
## Clear
|
||||
### Approve
|
||||
|
||||
Follows existing behaviour.
|
||||
See **Store**
|
||||
|
||||
If a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and the Bitbucket Authentication.DeleteCredentials() method is called to stored the passed in credentials.
|
||||
### Clear
|
||||
|
||||
## Delete
|
||||
Follows existing behavior.
|
||||
|
||||
Follows existing behaviour.
|
||||
If a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and the `Bitbucket.Authentication.DeleteCredentials()` method is called to stored the passed in credentials.
|
||||
|
||||
If a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and the Bitbucket Authentication.DeleteCredentials() method is called to stored the passed in credentials.
|
||||
### Delete
|
||||
|
||||
## Deploy
|
||||
Follows existing behavior.
|
||||
|
||||
If a Bitbucket URL is identified an instance of the `Bitbucket.Authentication` class is created and the `Bitbucket.Authentication.DeleteCredentials()` method is called to stored the passed in credentials.
|
||||
|
||||
### Deploy
|
||||
|
||||
Not effected by adding Bitbucket support.
|
||||
|
||||
## Erase
|
||||
### Erase
|
||||
|
||||
Follows existing behaviour.
|
||||
Follows existing behavior.
|
||||
|
||||
If a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and the Bitbucket Authentication.DeleteCredentials() method is called to stored the passed in credentials.
|
||||
If a Bitbucket URL is identified an instance of the `Bitbucket.Authentication` class is created and the `Bitbucket.Authentication.DeleteCredentials()` method is called to stored the passed in credentials.
|
||||
|
||||
## Fill
|
||||
### Fill
|
||||
|
||||
See Get
|
||||
See **Get**
|
||||
|
||||
## Get
|
||||
### Get
|
||||
|
||||
Follows existing behaviour.
|
||||
Follows existing behavior.
|
||||
|
||||
If a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and is used to attempt to:
|
||||
1. Get existing stored credentials using Authentication.GetGredentials()
|
||||
2. If that fails it prompts for Basic Auth credentials via Authentication.InteractiveLogon() and Bitbucket AuthenticationPrompts.CredentialModalPrompt()
|
||||
3. If that fails it, optionally, prompts of OAuth credentials via Authentication.InteractiveLogon() and Bitbucket AuthenticationPrompts.AuthenticationOAuthModalPrompt()
|
||||
If a Bitbucket URL is identified an instance of the `Bitbucket.Authentication` class is created and is used to attempt to:
|
||||
|
||||
Any credentials, retrieved from storage or entered by the user, are validated using Authentication.ValidateCredentials(). Only if the credentials pass validation are they returned to Git.
|
||||
1. Get existing stored credentials using `Bitbucket.Authentication.GetGredentials()`.
|
||||
2. If that fails it prompts for Basic Auth credentials via `Bitbucket.Authentication.InteractiveLogon()` and `Bitbucket.AuthenticationPrompts.CredentialModalPrompt()`.
|
||||
3. If that fails it, optionally, prompts of OAuth credentials via `Bitbucket.Authentication.InteractiveLogon()` and `Bitbucket.AuthenticationPrompts.AuthenticationOAuthModalPrompt()`.
|
||||
|
||||
## Install
|
||||
Any credentials, retrieved from storage or entered by the user, are validated using `Authentication.ValidateCredentials()`.
|
||||
Only if the credentials pass validation are they returned to Git.
|
||||
|
||||
See Deploy
|
||||
### Install
|
||||
|
||||
## Reject
|
||||
See **Deploy**
|
||||
|
||||
See Erase
|
||||
### Reject
|
||||
|
||||
## Remove
|
||||
See **Erase**
|
||||
|
||||
### Remove
|
||||
|
||||
Not effected by adding Bitbucket support.
|
||||
|
||||
## Store
|
||||
### Store
|
||||
|
||||
Follows existing behaviour.
|
||||
Follows existing behavior.
|
||||
|
||||
Then if a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and the Bitbucket Authentication.SetCredentials() method is called to stored the passed in credentials.
|
||||
Then if a Bitbucket URL is identified an instance of the Bitbucket Authentication class is created and the Bitbucket `Authentication.SetCredentials()` method is called to stored the passed in credentials.
|
||||
|
||||
## Uninstall
|
||||
### Uninstall
|
||||
|
||||
See Remove
|
||||
See **Remove**
|
||||
|
||||
## Version
|
||||
### Version
|
||||
|
||||
Not effected by adding Bitbucket suuport.
|
||||
Not effected by adding Bitbucket support.
|
||||
|
||||
# GCM Processes
|
||||
## GCM Processes
|
||||
|
||||
## Get Credentials
|
||||
### Get Credentials
|
||||
|
||||
Authentication.GetCredentials() will attempt to retrieve credentials, a username and some form of token either an access token or a password, from the Windows Credentials Manager.
|
||||
Because Bitbucket OAuth credentials include a stored refresh token, if the GCM is unable to retrieve the explicit credentials it will check to see if there is a stored refresh token. If one is found then it is used in an attempt to retrieve a new access token. If this is successful the new access and refresh tokens are stored and the access token is returned.
|
||||
`Authentication.GetCredentials()` will attempt to retrieve credentials, a username and some form of token either an access token or a password, from the Windows Credentials Manager.
|
||||
|
||||
Refresh tokens are stored in the Windows Credentials Manager by using a special URL as the key, this is generated by adding the suffix `/refresh_token`.
|
||||
Because Bitbucket OAuth credentials include a stored refresh token, if the GCM is unable to retrieve the explicit credentials it will check to see if there is a stored refresh token.
|
||||
If one is found then it is used in an attempt to retrieve a new access token.
|
||||
If this is successful the new access and refresh tokens are stored and the access token is returned.
|
||||
Refresh tokens are stored in the Windows Credential Manager by using a special URL as the key, this is generated by adding the suffix `/refresh_token`.
|
||||
|
||||
For example, the OAuth access token would be stored under the key "git:https://mminns@bitbucket.org/" and the refresh token would be stored under "git:https://mminns@bitbucket.org/refresh_token"
|
||||
For example, the OAuth access token would be stored under the key `git:https://mminns@bitbucket.org/` and the refresh token would be stored under `git:https://mminns@bitbucket.org/refresh_token`.
|
||||
|
||||
## Store Credentials
|
||||
### Store Credentials
|
||||
|
||||
When the GCM is instructed to store credentials for a Bitbucket URL the GCM will try and store default credentials for the host, i.e. for "git:https://bitbucket.org/", with a username. This effectively copies user specific credentials to the default host credentials. The GCM will also then check for a user specific refresh token, if it exists it will copy it to a new default host refresh token entry.
|
||||
When the GCM is instructed to store credentials for a Bitbucket URL the GCM will try and store default credentials for the host, i.e. for `git:https://bitbucket.org/`, with a username.
|
||||
This effectively copies user specific credentials to the default host credentials.
|
||||
The GCM will also then check for a user specific refresh token, if it exists it will copy it to a new default host refresh token entry.
|
||||
|
||||
If default host credentials already exist the GCM will NOT overwrite them.
|
||||
If default host credentials already exist the GCM will **not** overwrite them.
|
||||
|
||||
### Validate Credentials
|
||||
|
||||
## Validate Credentials
|
||||
|
||||
For Bitbucket URL the GCM will attempt to vaidate the credentials it has by making a call to the Bbucket REST API _https://api.bitbucket.org/2.0/user_. Because the the stored credentials do not contain any indication if they are for Basic Auth or OAuth the GCM will call first using Basic Auth headers and if that fails try with OAuth Bearer headers.
|
||||
For Bitbucket URL the GCM will attempt to validate the credentials it has by making a call to the Bitbucket REST API `_https://api.bitbucket.org/2.0/user_`.
|
||||
Because the the stored credentials do not contain any indication if they are for Basic Auth or OAuth the GCM will call first using Basic Auth headers and if that fails try with OAuth Bearer headers.
|
||||
Finally if the OAuth Bearer headers fail, the GCM will check to see if there is a refresh token available, if there is it will attempt to get a new access token and re-set the stored credentials to match that.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,15 @@
|
|||
# Configuration Options
|
||||
|
||||
GCM/Askpass work out of the box for most users. Configuration options are available to customize or tweak behavior(s).
|
||||
[Git Credential Manager](CredentialManager.md) and [Git Askpass](Askpass.md) 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 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`.
|
||||
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](EnvironmentVariables.md) 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.
|
||||
|
||||
|
|
@ -14,7 +19,7 @@ For example:
|
|||
|
||||
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 knows how to check for an apply, see the list below.
|
||||
For the complete list of settings the GCM understands, see the list below.
|
||||
|
||||
## Configuration Setting Names
|
||||
|
||||
|
|
@ -22,97 +27,149 @@ For the complete list of settings the GCM knows how to check for an apply, see t
|
|||
|
||||
Defines the type of authentication to be used.
|
||||
|
||||
Supports **Auto**, **Basic**, **AAD**, **MSA**, **GitHub**, **Integrated**, and **NTLM**.
|
||||
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 `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 `GitHub` if the host is 'github.com'.
|
||||
|
||||
Use **BitBucket** or **Atlassian** if the host is bitbucket.org.
|
||||
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.
|
||||
Use `Integrated` or `NTLM` if the host is a Team Foundation, or other NTLM authentication based, server.
|
||||
|
||||
Defaults to _Auto_.
|
||||
Defaults to `Auto`.
|
||||
|
||||
git config --global credential.microsoft.visualstudio.com.authority AAD
|
||||
|
||||
See [GCM_AUTHORITY](Environment.md#GCM_AUTHORITY)
|
||||
|
||||
### httpProxy
|
||||
|
||||
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.
|
||||
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:8080
|
||||
|
||||
See [HTTP_PROXY](Environment.md#HTTP_PROXY%20/%20HTTPS_PROXY)
|
||||
|
||||
### interactive
|
||||
|
||||
Specifies if user can be prompted for credentials or not.
|
||||
|
||||
Supports Auto, Always, or Never. Defaults to Auto.
|
||||
Supports `Auto`, `Always`, or `Never`. Defaults to `Auto`.
|
||||
|
||||
git config --global credential.microsoft.visualstudio.com.interactive never
|
||||
|
||||
See [GCM_INTERACTIVE](Environment.md#GCM_INTERACTIVE)
|
||||
|
||||
### modalPrompt
|
||||
|
||||
Forces authentication to use a modal dialog instead of asking for credentials at the command prompt.
|
||||
|
||||
Defaults to _true_.
|
||||
Supports `true` or `false`. Defaults to `true`.
|
||||
|
||||
git config --global credential.modalPrompt true
|
||||
|
||||
See [GCM_MODAL_PROMPT](Environment.md#GCM_MODAL_PROMPT)
|
||||
|
||||
### namespace
|
||||
|
||||
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 name
|
||||
|
||||
See [GCM_NAMESPACE](Environment.md#GCM_NAMESPACE)
|
||||
|
||||
### preserve
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Defaults to _false_.
|
||||
Supports `true` or `false`. Defaults to `false`.
|
||||
|
||||
git config --global credential.visualstudio.com.preserve true
|
||||
|
||||
See [GCM_PRESERVE](Environment.md#GCM_PRESERVE)
|
||||
|
||||
### tokenDuration
|
||||
|
||||
Sets a duration, in hours, limit for the validity of Personal Access Tokens requested from Visual Studio Team Services [VSTS].
|
||||
|
||||
If the value is greater than the maximum duration set for the account, the account value supercedes. The value cannot be less than a one hour (1).
|
||||
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 by _AAD_ and _MSA_ authorities.
|
||||
Defaults to the account token duration. Honored when authority is set to `AAD` or `MSA`.
|
||||
|
||||
git config --global credential.visualstudio.com.tokenDuration 24
|
||||
|
||||
See [GCM_TOKEN_DURATION](Environment.md#GCM_TOKEN_DURATION)
|
||||
|
||||
### useHttpPath
|
||||
|
||||
Causes the path portion of the target URI to considered meaningful.
|
||||
Instructs 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.
|
||||
|
||||
By default the path portion of the target URI is ignore, if this is set to true the path is considered meaningful and credentials will be store for each path.
|
||||
_Note:_ This option changes the behavior of Git.
|
||||
|
||||
Defaults to _false_.
|
||||
Supports `true` or `false`. Defaults to `false`.
|
||||
|
||||
git config --global credential.bitbucket.com.useHttpPath true
|
||||
|
||||
### username
|
||||
|
||||
Instructs 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](https://tools.ietf.org/html/rfc3986#section-3.2.1) 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 johndoe
|
||||
|
||||
### validate
|
||||
|
||||
Causes validation of credentials before supplying them to Git. Invalid credentials get a refresh attempt before failing. Incurs some minor overhead.
|
||||
Causes validation of credentials before supplying them to Git.
|
||||
Invalid credentials get a refresh attempt before failing.
|
||||
Incurs minor network operation overhead.
|
||||
|
||||
Defaults to _true_. Ignored by _Basic_ authority.
|
||||
Supports `true` or `false`. Defaults to `true`. Ignored when authority is set to `Basic`.
|
||||
|
||||
git config --global credential.microsoft.visualstudio.com.validate false
|
||||
|
||||
### writelog
|
||||
See [GCM_VALIDATE](Environment.md#GCM_VALIDATE)
|
||||
|
||||
Enables trace logging of all activities. Logs are written to the local .git/ folder at the root of the repository.
|
||||
### vstsScope
|
||||
|
||||
__Note:__ This setting will not override the **GCM_TRACE** environment variable.
|
||||
Overrides GCM default scope request when generating a Personal Access Token from Visual Studio Team Services [VSTS].
|
||||
The supported format is one or more [scope values](https://docs.microsoft.com/en-us/vsts/integrate/get-started/authentication/oauth#scopes) separated by whitespace, commas, semi-colons, or pipe `'|'` characters.
|
||||
|
||||
Defaults to _false_.
|
||||
Defaults to `vso.code_write|vso.packaging`; Honored when host is 'visualstudio.com'.
|
||||
|
||||
git config --global credential.writelog true
|
||||
git config --global credential.microsoft.visualstudio.com.vstsScope vso.code_write|vso.packaging_write|vso.test_write
|
||||
|
||||
See [GCM_VSTS_SCOPE](Environment.md#GCM_VSTS_SCOPE)
|
||||
|
||||
### writeLog
|
||||
|
||||
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 true
|
||||
|
||||
See [GCM_WRITELOG](Environment.md#GCM_WRITELOG)
|
||||
|
||||
## Sample Configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -1,60 +1,65 @@
|
|||
# Git Credential Manager for Windows
|
||||
|
||||
The [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (GCM) provides secure Git credential storage for Windows. GCM provides multi-factor authentication support for [Visual Studio Team Services](https://www.visualstudio.com/), [Team Foundation Server](https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx), [GitHub](https://github.com/), and [BitBucket](https://bitbucket.org).
|
||||
The [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (GCM) provides secure Git credential storage for Windows.
|
||||
GCM provides multi-factor authentication support for [Visual Studio Team Services](https://www.visualstudio.com/), [Team Foundation Server](https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx), [GitHub](https://github.com/), and [BitBucket](https://bitbucket.org).
|
||||
|
||||
## Usage
|
||||
|
||||
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.
|
||||
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.
|
||||
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>]]
|
||||
`git credential-manager [<command> [<args>]]`
|
||||
|
||||
## Commands
|
||||
|
||||
### delete
|
||||
|
||||
Removes stored credentials for a given URL. Any future attempts to authenticate with the remote will require authentication steps to be completed again.
|
||||
Removes stored credentials for a given URL.
|
||||
Any future attempts to authenticate with the remote will require authentication steps to be completed again.
|
||||
|
||||
### deploy _\[--path \<installation_path\>\] \[--passive\] \[--force\]_
|
||||
|
||||
Deploys the Git Credential Manager for Windows package and sets Git configuration to use the helper.
|
||||
|
||||
#### --path \<installation_path\>
|
||||
#### deploy --path \<installation_path\>
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
#### --passive
|
||||
#### deploy --passive
|
||||
|
||||
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.
|
||||
When combined with `--force` all output is eliminated; only the return code can be used to validate success.
|
||||
|
||||
#### --force
|
||||
#### deploy --force
|
||||
|
||||
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.
|
||||
When combined with `--passive` all output is eliminated; only the return code can be used to validate success.
|
||||
|
||||
### remove _\[--path \<installation_path\>\] \[--passive\] \[--force\]_
|
||||
|
||||
Removes the Git Credential Manager for Windows package and unsets Git configuration to no longer use the helper.
|
||||
|
||||
#### --path \<installation_path\>
|
||||
#### remove --path \<installation_path\>
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
#### --passive
|
||||
#### remove --passive
|
||||
|
||||
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.
|
||||
When combined with `--force` all output is eliminated; only the return code can be used to validate success.
|
||||
|
||||
#### --force
|
||||
#### remove --force
|
||||
|
||||
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.
|
||||
When combined with `--passive` all output is eliminated; only the return code can be used to validate success.
|
||||
|
||||
### version
|
||||
|
||||
|
|
|
|||
|
|
@ -9,52 +9,67 @@ The easiest way to get started is to:
|
|||
1. Install Visual Studio.
|
||||
2. [Clone the repository](https://github.com/Microsoft/Git-Credential-Manager-for-Windows.git).
|
||||
3. Open the solution file (GitCredentialManager.sln) using Visual Studio.
|
||||
4. Right-click the solution node in Solution Explorer and choose 'Restore NuGet Packages'. This will download and setup all of the dependencies.
|
||||
4. Right-click the solution node in Solution Explorer and choose 'Restore NuGet Packages'.
|
||||
This will download and setup all of the dependencies.
|
||||
5. Right-click the 'Cli-CredentialHelper' project in Solution Explorer and select 'Properties'.
|
||||
6. In the "Properties" window, select the 'Debug' tab from the left side.
|
||||
7. In the "Properties: Debug" window, add the word "get" to the 'Command line arguments:' text box.
|
||||
6. In the 'Properties' window, select the 'Debug' tab from the left side.
|
||||
7. In the 'Properties: Debug' window, add the word "get" to the 'Command line arguments:' text box.
|
||||
8. Close the "Properties" window.
|
||||
5. Hit \<F5\>, or 'Debug' \>\> 'Start Debugging' from the top menu of Visual Studio.
|
||||
9. Hit \<F5\>, or 'Debug' \>\> 'Start Debugging' from the top menu of Visual Studio.
|
||||
|
||||
### Debugging Code
|
||||
|
||||
Once the GCM starts you'll be presented with a very *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.
|
||||
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:
|
||||
|
||||
```
|
||||
```ini
|
||||
protocol=https
|
||||
host=github.com
|
||||
|
||||
|
||||
```
|
||||
|
||||
Notice the **blank last line**. That empty line is how Git and the GCM notify the otherside that they're done sending data. Until an empty line is sent to the GCM, it'll keep attempting to read from standard input.
|
||||
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.
|
||||
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 `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.
|
||||
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.
|
||||
|
||||
### Notable Code
|
||||
|
||||
* `Program.LoadOperationArguments` method is where the GCM scans, parses, and consumes environmental and configuraiton setting values.
|
||||
* `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.
|
||||
|
||||
## Installer (setup.exe)
|
||||
|
||||
Changes to the installer (setup.exe) requires [Inno Setup Compiler 5.5.9](http://www.jrsoftware.org/isinfo.php) or later to compile. Additionally, the [IDP plugin for Inno Setup](https://mitrichsoftware.wordpress.com/inno-setup-tools/inno-download-plugin/) is also required.
|
||||
Changes to the installer (setup.exe) requires [Inno Setup Compiler 5.5.9](http://www.jrsoftware.org/isinfo.php) or later to compile.
|
||||
Additionally, the [IDP plugin for Inno Setup](https://mitrichsoftware.wordpress.com/inno-setup-tools/inno-download-plugin/) 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 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.
|
||||
|
||||
## Microsoft.Alm.Authentication NuGet Package
|
||||
|
||||
The [Microsoft.Alm.Authentication](https://www.nuget.org/packages/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 symbold packages are automatically created.
|
||||
The [Microsoft.Alm.Authentication](https://www.nuget.org/packages/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.
|
||||
|
||||
## Signing
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Documents
|
||||
|
||||
|
|
@ -78,9 +93,13 @@ Additionally, the GCM outputs *GIT_TRACE* compatible logging. To use the *GIT_TR
|
|||
|
||||
1. Open a Command Prompt.
|
||||
2. Run `setx GCM_TRACE %UserProfile%\git.log`; this will cause the GCM to log to a file located at "%UserProfile%\git.log".
|
||||
3. If you'd like Git to interleave its traces as well run `setx GIT_TRACE %UserProfile%\git.log`; now Git will log to the file located at "%UserProfile%\git.log".
|
||||
3. Close and re-open any console windows, and restart any application which need to make use of the new environment variable.
|
||||
4. If you'd like Git to interleave its traces as well run `setx GIT_TRACE %UserProfile%\git.log`; now Git will log to the file located at "%UserProfile%\git.log".
|
||||
5. To remove the environment variable, run `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%\my 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 acccess to; for example paths like "%ProgramFiles%\Git\logs\trace.log" are not recommended because only elevated processes can write to "%ProgramFiles%".
|
||||
__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%\my 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%\Git\logs\trace.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.
|
||||
|
||||
|
|
@ -94,13 +113,19 @@ There are many ways to contribute.
|
|||
|
||||
### Code Contributions
|
||||
|
||||
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.
|
||||
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](https://cla.microsoft.com/cladoc/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.
|
||||
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](https://cla.microsoft.com/cladoc/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.
|
||||
|
||||
### Code of Conduct
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact <opencode@microsoft.com> with any additional questions or comments.
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact <opencode@microsoft.com> with any additional questions or comments.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,152 @@
|
|||
# Environment Variables
|
||||
|
||||
[Git Credential Manager](CredentialManager.md) and [Git Askpass](Askpass.md) work out of the box for most users.
|
||||
Environment variables, to customize or tweak behavior, are available as needed.
|
||||
|
||||
The Git Credential Manager for Windows [GCM] can be configured using [environment variables](https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx). Environment variables take precedence over [configuration](Configuration.md) settings.
|
||||
|
||||
For the complete list of environment variables the GCM understands, see the list below.
|
||||
|
||||
## Configuration Setting Names
|
||||
|
||||
### GCM_AUTHORITY
|
||||
|
||||
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`.
|
||||
|
||||
### GCM_CONFIG_NOLOCAL
|
||||
|
||||
Determines if the the GCM should ignore Git local configuration values.
|
||||
|
||||
Supports `true` or `false`. Defaults to `false`.
|
||||
|
||||
_No configuration equivalent._
|
||||
|
||||
### GCM_CONFIG_NOSYSTEM
|
||||
|
||||
Determines if the the GCM should ignore Git system configuration values.
|
||||
|
||||
Supports `true` or `false`. Defaults to `false`.
|
||||
|
||||
_No configuration equivalent._
|
||||
|
||||
### HTTP_PROXY / HTTPS_PROXY
|
||||
|
||||
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.
|
||||
|
||||
See [credential.httpProxy](Configuration.md#httpProxy).
|
||||
|
||||
### GCM_HTTP_USER_AGENT
|
||||
|
||||
Sets the reported [user-agent](https://en.wikipedia.org/wiki/User_agent) when GCM performs network operations.
|
||||
|
||||
Defaults to the GCM's user-agent.
|
||||
|
||||
_No configuration equivalent._
|
||||
|
||||
### GCM_INTERACTIVE
|
||||
|
||||
Specifies if user can be prompted for credentials or not.
|
||||
|
||||
Supports `Auto`, `Always`, or `Never`. Defaults to `Auto`.
|
||||
|
||||
See [credential.interactive](Configuration.md#interactive).
|
||||
|
||||
### GCM_MODAL_PROMPT
|
||||
|
||||
Forces authentication to use a modal dialog instead of asking for credentials at the command prompt.
|
||||
|
||||
Supports `true` or `false`. Defaults to `true`.
|
||||
|
||||
See [credential.modalPrompt](Configuration.md#modalPrompt).
|
||||
|
||||
### GCM_NAMESPACE
|
||||
|
||||
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.
|
||||
|
||||
See [credential.namespace](Configuration.md#namespace).
|
||||
|
||||
### GCM_PRESERVE
|
||||
|
||||
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`.
|
||||
|
||||
See [credential.preserve](Configuration.md#preserve).
|
||||
|
||||
### GCM_TOKEN_DURATION
|
||||
|
||||
Sets a duration, in hours, limit for the validity of Personal Access Tokens requested from Visual Studio Team Services [VSTS].
|
||||
|
||||
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`.
|
||||
|
||||
See [credential.tokenDuration](Configuration.md#tokenDuration).
|
||||
|
||||
### GCM_TRACE
|
||||
|
||||
Enables trace logging of all activities.
|
||||
Configuring Git and the GCM to trace to the same location is often desirable, and the GCM is compatible and cooperative with `GIT_TRACE`.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
SET GIT_TRACE=%UserProfile%\git.log
|
||||
SET GCM_TRACE=%UserProfile%\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`, logs are written standard error.
|
||||
|
||||
Defaults tracing being disabled.
|
||||
|
||||
_No configuration equivalent._
|
||||
|
||||
### GCM_VALIDATE
|
||||
|
||||
Causes validation of credentials before supplying them to Git.
|
||||
Invalid credentials get a refresh attempt before failing.
|
||||
Incurs minor network operation overhead.
|
||||
|
||||
Defaults to `true`. Ignored when authority set to `Basic`.
|
||||
|
||||
See [credential.validate](Configuration.md#validate).
|
||||
|
||||
### GCM_VSTS_SCOPE
|
||||
|
||||
Overrides GCM default scope request when generating a Personal Access Token from Visual Studio Team Services [VSTS].
|
||||
The supported format is one or more [scope values](https://docs.microsoft.com/en-us/vsts/integrate/get-started/authentication/oauth#scopes) separated by whitespace, commas, semi-colons, or pipe characters (`' '`, `','`, `';'`, `'|'`).
|
||||
|
||||
Defaults to `vso.code_write|vso.packaging`; Honored when host is 'visualstudio.com'.
|
||||
|
||||
See [credential.vstsScope](Configuration.md#vstsScope).
|
||||
|
||||
### GCM_WRITELOG
|
||||
|
||||
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.
|
||||
|
||||
See [credential.writeLog](Configuration.md#writeLog).
|
||||
89
Docs/Faq.md
89
Docs/Faq.md
|
|
@ -4,73 +4,108 @@ If you have an issue using GCM or Askpass, please review the following FAQ and c
|
|||
|
||||
## Q: Why am always prompted for my username and password?
|
||||
|
||||
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, 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`.
|
||||
|
||||
## Q: Why does my GUI freeze when I push, pull, or fetch?
|
||||
|
||||
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](Configuration.md#modalprompt).
|
||||
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](Configuration.md#modalprompt).
|
||||
|
||||
1. Decide if you want this to be a global setting (all of your repositories) or a local setting (just one repository).
|
||||
2. Start your favorite shell. (cmd, powershell, bash, etc.)
|
||||
2. Start your favorite shell (CMD, PowerShell, bash, etc.).
|
||||
3. 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 repository setting, `cd` to your repo and in that repo run `git config credential.modalprompt true`.
|
||||
* If you’ve decided this is a global setting run `git config --global credential.modalprompt true`.
|
||||
* If you’ve decided this a per repository setting, `cd` to your repo and in that repo run `git config credential.modalprompt true`.
|
||||
|
||||
## Q: Why am I not seeing my SSH keys being saved?
|
||||
|
||||
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 comment on the [SSH Key support issue](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/issues/25) which is already open.
|
||||
The Git Credential Manager supports caching of SSH key password through [git-askpass](Askpass.md).
|
||||
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](https://github.com/dahlbyk/posh-git) support automatic startup of 'ssh-agent.exe' which does assist with SSH certificate password caching.
|
||||
|
||||
## Q: Is there a NuGet Package available?
|
||||
|
||||
Yes there is: <https://www.nuget.org/packages/Microsoft.Alm.Authentication>. It only supports the core authentication library, but if you're looking to extend the GCM then it is likely exactly what you're after.
|
||||
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.
|
||||
|
||||
## Q: Why doesn’t Git Credential Manager work on Windows XP, Mac OS, or Linux?
|
||||
|
||||
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](https://www.visualstudio.com/en-us/products/visual-studio-team-services-vs.aspx) we had to use the [Azure Directory Authentication Libraries](https://github.com/AzureAD) 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.
|
||||
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](https://www.visualstudio.com/en-us/products/visual-studio-team-services-vs.aspx) we had to use the [Azure Directory Authentication Libraries](https://github.com/AzureAD) 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.
|
||||
|
||||
## Q: Will there ever be support for Windows XP, Mac OS, or Linux?
|
||||
|
||||
We can safely say that we have no interest in supporting Windows XP. Even [Microsoft has ended support for Windows XP](https://windows.microsoft.com/en-us/windows/end-support-help). Support for Mac OS and Linux are handled by [Microsoft Git Credential Manager for Mac and Linux](https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux).
|
||||
We can safely say that we have no interest in supporting Windows XP.
|
||||
Even [Microsoft has ended support for Windows XP](https://windows.microsoft.com/en-us/windows/end-support-help).
|
||||
Support for Mac OS and Linux are handled by [Microsoft Git Credential Manager for Mac and Linux](https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux).
|
||||
|
||||
## Q: Why is my distribution/version of Git not supported? Why is Git for Windows favored?
|
||||
|
||||
The Credential Manager deployment helpers (`install.cmd` and `Setup.exe`) are focused on support for [Git for Windows](https://github.com/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.
|
||||
The Credential Manager deployment helpers (`install.cmd` and `Setup.exe`) are focused on support for [Git for Windows](https://github.com/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.
|
||||
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.
|
||||
|
||||
1. Copy the contents of the `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`.
|
||||
1. Copy the contents of the `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`.
|
||||
2. Update your Git configuration by running `git config --global credential.helper manager`.
|
||||
|
||||
## Q: I thought Microsoft was maintaining this, why does the GCM not work as expected with TFS?
|
||||
|
||||
Team Foundation Server, when deployed on a corporate Active Directory, uses the [Microsoft Kerberos](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378747(v=vs.85).aspx) protocol for authentication. Git doesn't "speak" the Kerberos protocol.
|
||||
Team Foundation Server, when deployed on a corporate Active Directory, uses the [Microsoft Kerberos](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378747(v=vs.85).aspx) protocol for authentication.
|
||||
Git hasn't traditionally be able to "speak" the Kerberos protocol.
|
||||
However, starting with [v1.14.0](https://github.com/git-for-windows/git/releases/tag/v2.14.0.windows.1) Git for Windows supports Microsoft [Secure Channel](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380123(v=vs.85).aspx).
|
||||
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 can be convinced to "forward" credentials by supplying a blank credentials (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.
|
||||
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.integrated true`, where `my-tfs` can be replaced by the name of your TFS server; the port number is not required for GCM configuration but you will want it for the Git remote.
|
||||
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.
|
||||
|
||||
Once updated, the new configuration tells the GCM to only forward domain credentials. If you set `credential.integrated true`, every domain will be assumed to support domain 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.
|
||||
_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.
|
||||
|
||||
## Q: Why doesn't SourceTree use the credentials in the GCM?
|
||||
|
||||
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.
|
||||
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.
|
||||
To fix this go to 'Tools > Options > Git' and click the 'Use System Git' button.
|
||||
This works in v1.8.3.0 of SourceTree.
|
||||
|
||||
## Q: Why is Git not using the GCM in some of my repositories (but instead using SSH authentication)?
|
||||
|
||||
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 VSTS, TFS, GitHub or Bitbucket, and then run `git remote set-url origin <url>`, where `<url>` is the HTTP(S) URL.
|
||||
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 VSTS, TFS, GitHub or Bitbucket, and then run `git remote set-url origin <url>`, where `<url>` is the HTTP(S) URL.
|
||||
|
||||
## Q: Why is git.exe failing to authenticate after linking/unlinking your Visual Studio Team Services account from Azure Active Directory?
|
||||
|
||||
When the tenant backing the Visual Studio Team Services (VSTS) account changes like when you [Connect VSTS account to Azure Active Directory (Azure AD)](https://docs.microsoft.com/en-us/vsts/accounts/connect-account-to-aad), the tenant cache needs to be cleared. This can be corrected by simply deleting the *%LocalAppData%\GitCredentialManager\tenant.cache* file on each machine returning a login error like below. The GCM will automatically reacted the file as needed on subsequent login attempts.
|
||||
When the tenant backing the Visual Studio Team Services (VSTS) account changes like when you [Connect VSTS account to Azure Active Directory (Azure AD)](https://docs.microsoft.com/en-us/vsts/accounts/connect-account-to-aad), 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%\GitCredentialManager\tenant.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**
|
||||
Opening repositories:
|
||||
C:\XXXXXXXXXX
|
||||
Example:
|
||||
|
||||
```text
|
||||
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://XXXXXXXX.visualstudio.com’: terminal prompts disabled
|
||||
Pushing to https://XXXXXXXX.visualstudio.com/_git/XXXXXX
|
||||
|
||||
Log from git bash : Login failed.
|
||||
could not read Username for ‘https://******.********.***’: terminal prompts disabled
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# Git Credential Manager for Windows
|
||||
|
||||
The [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (GCM) provides secure Git credential storage for Windows. GCM provides multi-factor authentication support for [Visual Studio Team Services](https://www.visualstudio.com/), [Team Foundation Server](Faq.md#q-i-thought-microsoft-was-maintaining-this-why-does-the-gcm-not-work-as-expected-with-tfs), and [GitHub](https://github.com/).
|
||||
The [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (GCM) provides secure Git credential storage for Windows.
|
||||
GCM provides multi-factor authentication support for [Visual Studio Team Services](https://www.visualstudio.com/), [Team Foundation Server](Faq.md#q-i-thought-microsoft-was-maintaining-this-why-does-the-gcm-not-work-as-expected-with-tfs), and [GitHub](https://github.com/).
|
||||
|
||||
This project includes:
|
||||
|
||||
|
|
@ -12,32 +13,44 @@ This project includes:
|
|||
* Kerberos authentication for Team Foundation Server ([see notes](#q-i-thought-microsoft-was-maintaining-this-why-does-the-gcm-not-work-as-expected-with-tfs))
|
||||
* 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](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/wiki/How-the-Git-Credential-Managers-works).
|
||||
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](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/wiki/How-the-Git-Credential-Managers-works).
|
||||
|
||||
## Download and Install
|
||||
|
||||
To use the GCM, you can download the [latest installer](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases/latest). To install, double-click Setup.exe and follow the instructions presented.
|
||||
To use the GCM, you can download the [latest installer](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases/latest).
|
||||
To install, double-click Setup.exe and follow the instructions presented.
|
||||
|
||||
When prompted to select your terminal emulator for Git Bash you should choose the Windows' default console window, or make sure GCM is [configured to use modal dialogs](Configuration.md#modalprompt). GCM cannot prompt you for credentials, at the console, in a MinTTY setup.
|
||||
When prompted to select your terminal emulator for Git Bash you should choose the Windows' default console window, or make sure GCM is [configured to use modal dialogs](Configuration.md#modalprompt).
|
||||
GCM cannot prompt you for credentials, at the console, in a MinTTY setup.
|
||||
|
||||
## How to use
|
||||
|
||||
You don't. It [magically](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/issues/31) works when credentials are needed. For example, when pushing to [Visual Studio Team Services](https://www.visualstudio.com), it automatically opens a window and initializes an oauth2 flow to get your token.
|
||||
You don't.
|
||||
It [magically](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/issues/31) works when credentials are needed.
|
||||
For example, when pushing to [Visual Studio Team Services](https://www.visualstudio.com), it automatically opens a window and initializes an oauth2 flow to get your token.
|
||||
|
||||
### Manual Installation
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### Build and Install from Sources
|
||||
|
||||
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`.
|
||||
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](Configuration.md) 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.
|
||||
[Various options](Configuration.md) 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.
|
||||
|
||||
#### Additional Resources
|
||||
|
||||
* [Configuration Options](Configuration.md)
|
||||
* [Usage Options](CredentialManager.md)
|
||||
* [Environmental Variables](Environment.md)
|
||||
* [Build Agent and Automation Support](Automation.md)
|
||||
* [Frequently Asked Questions](Faq.md)
|
||||
* [Development and Debugging](Development.md)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче