Skip to content

Commit 4bcb796

Browse files
mjcheethammjcheetham
authored
Merge pull request #39 from microsoft/master
Merge master to release including #29, #30, #32, #33, #34, #35
2 parents 3ad6ec1 + 3d880cb commit 4bcb796

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+2449
-486
lines changed

‎.azure-pipelines/templates/osx/pack.signed/step1-layout.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
steps:
2-
- script: src/osx/Installer.Mac/layout.sh --configuration='$(configuration)' --output='$(Build.StagingDirectory)/payload'
2+
- script: src/osx/Installer.Mac/layout.sh --configuration='$(configuration)' --output='$(Build.StagingDirectory)/payload' --symbol-output='$(Build.StagingDirectory)/symbols'
33
displayName: Layout installer payload
44

55
- task: PublishPipelineArtifact@0
66
displayName: Upload unsigned payload
77
inputs:
88
artifactName: 'tmp.macpayload_unsigned'
99
targetPath: '$(Build.StagingDirectory)/payload'
10+
11+
- task: PublishPipelineArtifact@0
12+
displayName: Upload symbols
13+
inputs:
14+
artifactName: 'Symbols.Mac'
15+
targetPath: '$(Build.StagingDirectory)/symbols'

‎.github/ISSUE_TEMPLATE/auth-problem.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
name: Authentication failure
3+
about: An authentication problem occurred when running a Git command.
4+
title: ''
5+
labels: 'auth-failure'
6+
assignees: ''
7+
---
8+
9+
**Which version of GCM Core are you using?**
10+
11+
From a terminal, run `git-credential-manager version` and paste the output.
12+
13+
<!-- Ex:
14+
Git Credential Manager version 2.0.8-beta+e1f8492d04 (macOS, .NET Core 4.6.27129.04)
15+
-->
16+
17+
**Which Git host provider are you trying to connect to?**
18+
19+
* [ ] Azure DevOps
20+
* [ ] Azure DevOps Server (TFS/on-prem)
21+
* [ ] GitHub
22+
* [ ] GitHub Enterprise
23+
* [ ] BitBucket
24+
* [ ] Other - please describe
25+
26+
**Can you access the remote repository directly in the browser using the remote URL?**
27+
28+
From a terminal, run `git remote -v` to see your remote URL.
29+
30+
<!-- Ex:
31+
origin https://dev.azure.com/contoso/_git/widgets
32+
-->
33+
34+
* [ ] Yes
35+
* [ ] No, I get a permission error
36+
* [ ] No, for a different reason - please describe
37+
38+
---
39+
40+
**_[Azure DevOps only]_ What format is your remote URL?**
41+
42+
* [ ] Not applicable
43+
* [ ] https://dev.azure.com/`{org}`/...
44+
* [ ] https://`{org}`@dev.azure.com/`{org}`/...
45+
* [ ] https://`{org}`.visualstudio.com/...
46+
47+
**_[Azure DevOps only]_ If the account picker shows more than one identity as you authenticate, check that you selected the same one that has access on the web.**
48+
49+
* [ ] Not applicable
50+
* [ ] I only see one identity
51+
* [ ] I checked each identity and none worked
52+
53+
---
54+
55+
**Expected behavior**
56+
57+
I am authenticated and my Git operation completes successfully.
58+
59+
**Actual behavior**
60+
61+
A clear and concise description of what happens. For example: exception is thrown, UI freezes, etc.
62+
63+
**Logs**
64+
65+
Set the environment variables `GCM_TRACE=1` and `GIT_TRACE=1` and re-run your Git command. Review and redact any private information and attach the log.

‎.github/ISSUE_TEMPLATE/feature-req.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
name: Feature request
3+
about: A suggestion for a new feature in Git Credential Manager Core.
4+
title: ''
5+
labels: 'enhancement'
6+
assignees: ''
7+
---
8+
9+
**Feature description**
10+
11+
A clear and concise description of the new feature.

‎README.md‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,65 @@
1-
# Git Credential Manager (.NET Core)
1+
# Git Credential Manager Core
22

33
Branch|Status
44
-|-
55
master|[![Build Status](https://mseng.visualstudio.com/AzureDevOps/_apis/build/status/Teams/VCDesktop/Git-Credential-Manager-Core/GCM-CI?branchName=master)](https://mseng.visualstudio.com/AzureDevOps/_build/latest?definitionId=7861&branchName=master)
66

7+
---
8+
9+
[Git Credential Manager Core](https://github.com/Microsoft/Git-Credential-Manager-Core) (GCM Core) is a secure Git credential helper built on [.NET Core](https://microsoft.com/dotnet) that runs on Windows, macOS and Linux.
10+
11+
Compared to Git's [built-in credential helpers]((https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)) (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM Core provides multi-factor authentication support for [Azure DevOps](https://dev.azure.com/), Azure DevOps Server (formerly Team Foundation Server), and GitHub.
12+
13+
## Public preview for macOS
14+
15+
The long-term goal of GCM Core is to converge the .NET Framework-based [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) (GCM Windows), and the Java-based [Git Credential Manager for Mac and Linux](https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux) (Java GCM), providing a consistent authentication experience across all platforms.
16+
17+
### Current status
18+
19+
GCM Core is currently in preview for the macOS platform only, with a Windows and Linux preview following in due course. Until that time we recommend Windows users to continue to use GCM Windows, and Linux users to use preferably SSH or Java GCM.
20+
21+
Feature|Windows|macOS|Linux
22+
-|-|-|-
23+
Installer/uninstaller||&#10003;|
24+
Secure platform credential storage|&#10003;<br/>Windows Credential Manager|&#10003;<br/>macOS Keychain|
25+
Multi-factor authentication support for Azure DevOps|&#10003;|&#10003;|
26+
Two-factor authentication support for GitHub|&#10003;\*|&#10003;\*|&#10003;\*
27+
Two-factor authentication support for BitBucket|||
28+
Windows Integrated Authentication (NTLM/Kerberos) support|&#10003;|_N/A_|_N/A_
29+
Basic HTTP authentication support|&#10003;|&#10003;|&#10003;
30+
31+
**Notes:**
32+
33+
(\*) Currently only supported when using Git from the terminal or command line. A platform-native UI experience for GitHub is not yet available on macOS, but planned.
34+
35+
### Planned features
36+
37+
- [ ] Windows and Linux installers
38+
- [ ] Improved GitHub support (platform-native UI)
39+
- [ ] BitBucket
40+
- [ ] Proxy support
41+
42+
## Download and Install
43+
44+
To use GCM Core, you can download the [latest installer](https://github.com/Microsoft/Git-Credential-Manager-Core/releases/latest) for your platform. To install, double-click installation package and follow the instructions presented.
45+
46+
## How to use
47+
48+
You don't! GCM gets called when Git needs credentials for an operation. For example, when pushing (`git push`) to [Azure DevOps](https://dev.azure.com), it automatically opens a window and initializes an OAuth2 flow to get your personal access token.
49+
50+
## Additional Resources
51+
52+
- [Frequently asked questions](docs/faq.md)
53+
- [Development and debugging](docs/development.md)
54+
- [Command-line usage](docs/usage.md)
55+
- [Configuration options](docs/configuration.md)
56+
- [Environment variables](docs/environment.md)
57+
758
## Contributing
859

960
This project welcomes contributions and suggestions. Most contributions require you to agree to a
1061
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
11-
the rights to use your contribution. For details, visit https://cla.microsoft.com.
62+
the rights to use your contribution. For details, visit <https://cla.microsoft.com.>
1263

1364
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
1465
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions

‎docs/configuration.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Configuration options
2+
3+
[Git Credential Manager Core](usage.md) works out of the box for most users.
4+
5+
Git Credential Manager Core (GCM Core) can be configured using Git's configuration files, and follows all of the same rules Git does when consuming the files.
6+
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. All of GCM Core's configuration settings begin with the term `credential`.
7+
8+
GCM Core honors several levels of settings, in addition to the standard local \> global \> system tiering Git uses.
9+
URL-specific settings or overrides can be applied to any value in the `credential` namespace with the syntax below.
10+
11+
Additionally, GCM Core respects several GCM-specific [environment variables](environment.md) **which take precedence over configuration options.**
12+
13+
GCM Core will only be used by Git if it is installed and configured (`credential.helper`).
14+
15+
**Example:**
16+
17+
> `credential.microsoft.visualstudio.com.namespace` is more specific than `credential.visualstudio.com.namespace`, which is more specific than `credential.namespace`.
18+
19+
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'.
20+
21+
For the complete list of settings GCM Core understands, see the list below.
22+
23+
## Available settings
24+
25+
_Currently there are no available settings. This is a placeholder for the settings on the backlog._

‎docs/development.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Development and debugging
2+
3+
??

‎docs/environment.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Environment variables
2+
3+
[Git Credential Manager Core](usage.md) work out of the box for most users. Configuration options are available to customize or tweak behavior.
4+
5+
Git Credential Manager Core (GCM Core) can be configured using environment variables. **Environment variables take precedence over [configuration](configuration.md) options.**
6+
7+
For the complete list of environment variables GCM Core understands, see the list below.
8+
9+
## Available settings
10+
11+
### GCM_TRACE
12+
13+
Enables trace logging of all activities.
14+
Configuring Git and GCM to trace to the same location is often desirable, and GCM is compatible and cooperative with `GIT_TRACE`.
15+
16+
#### Example
17+
18+
##### Windows
19+
20+
```batch
21+
SET GIT_TRACE=%UserProfile%\git.log
22+
SET GCM_TRACE=%UserProfile%\git.log
23+
```
24+
25+
##### macOS/Linux
26+
27+
```bash
28+
export GIT_TRACE=$HOME/git.log
29+
export GCM_TRACE=$HOME/git.log
30+
```
31+
32+
If the value of `GCM_TRACE` is a full path to a file in an existing directory, logs are appended to the file.
33+
34+
If the value of `GCM_TRACE` is `true` or `1`, logs are written to standard error.
35+
36+
Defaults to tracing disabled.
37+
38+
_No configuration equivalent._
39+
40+
### GCM_TRACE_SECRETS
41+
42+
Enables tracing of secret and senstive information, which is by default masked in trace output.
43+
Requires that `GCM_TRACE` is also enabled.
44+
45+
#### Example
46+
47+
##### Windows
48+
49+
```batch
50+
SET GCM_TRACE=%UserProfile%\gcm.log
51+
SET GCM_TRACE_SECRETS=1
52+
```
53+
54+
##### macOS/Linux
55+
56+
```bash
57+
export GCM_TRACE=$HOME/gcm.log
58+
export GCM_TRACE_SECRETS=1
59+
```
60+
61+
If the value of `GCM_TRACE_SECRETS` is `true` or `1`, trace logs will include secret information.
62+
63+
Defaults to disabled.
64+
65+
_No configuration equivalent._
66+
67+
### GCM_TRACE_MSAUTH
68+
69+
Enables inclusion of Microsoft Authentication libraries (ADAL, MSAL) logs in GCM trace output.
70+
Requires that `GCM_TRACE` is also enabled.
71+
72+
#### Example
73+
74+
##### Windows
75+
76+
```batch
77+
SET GCM_TRACE=%UserProfile%\gcm.log
78+
SET GCM_TRACE_MSAUTH=1
79+
```
80+
81+
##### macOS/Linux
82+
83+
```bash
84+
export GCM_TRACE=$HOME/gcm.log
85+
export GCM_TRACE_MSAUTH=1
86+
```
87+
88+
If the value of `GCM_TRACE_MSAUTH` is `true` or `1`, trace logs will include verbose ADAL/MSAL logs.
89+
90+
Defaults to disabled.
91+
92+
_No configuration equivalent._
93+
94+
### GCM_DEBUG
95+
96+
Pauses execution of GCM Core at launch to wait for a debugger to be attached.
97+
98+
#### Example
99+
100+
##### Windows
101+
102+
```batch
103+
SET GCM_DEBUG=1
104+
```
105+
106+
##### macOS/Linux
107+
108+
```bash
109+
export GCM_DEBUG=1
110+
```
111+
112+
Defaults to disabled.
113+
114+
_No configuration equivalent._

‎docs/faq.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Frequently asked questions
2+
3+
## Authentication problems
4+
5+
### Q: I got an error trying to push/pull/clone. What do I do now?
6+
7+
Please follow these steps to diagnose or resolve the problem:
8+
9+
1. Check if you can access the remote repository in a web browser. If you cannot, this is probably a permission problem and you should follow up with the repository administrator for access. Execute `git remote -v` from a terminal to show the remote URL.
10+
11+
1. If you are experiencing a Git authentication problem using an editor, IDE or other tool, try performing the same operation from the terminal. Does this still fail? If the operation succeeds from the terminal please include details of the specific tool and version in any issue reports.
12+
13+
1. Set the environment variable `GCM_TRACE` and run the Git operation again. Find instructions [here](environment.md#GCM_TRACE).
14+
15+
1. If all else fails, create an issue [here](https://github.com/Microsoft/Git-Credential-Manager-Core/issues/create), making sure to include the trace log.
16+
17+
### Q: I got an error saying unsecure HTTP is not supported.
18+
19+
To keep your data secure, Git Credential Manager Core will not send credentials for Azure Repos, Azure DevOps Server (TFS), GitHub, and BitBucket, over HTTP connections that are not secured using TLS (HTTPS).
20+
21+
Please make sure your remote URLs use "https://" rather than "http://".
22+
23+
## About the project
24+
25+
### Q: How does project this relate to [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) and [Git Credential Manager for Mac and Linux](https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux)?
26+
27+
Git Credential Manager for Windows (GCM Windows) is a .NET Framework-based Git credential helper which runs on Windows.
28+
Likewise the Git Credential Manager for Mac and Linux (Java GCM) is a Java-based Git credential helper that runs only on macOS and Linux. Although both of these projects aim to solve the same problem (providing seamless multi-factor HTTPS authentication with Git), they are based on different codebases and languages which is becoming hard to manage to ensure feature parity.
29+
30+
Git Credential Manager Core (GCM Core; this project) aims to replace both GCM Windows and Java GCM with a unified codebase which should be easier to maintain and enhance in the future.
31+
32+
### Q: Does this mean GCM for Windows (.NET Framework-based) is deprecated?
33+
34+
No. Git Credential Manager for Windows (GCM Windows) will continue to be supported until such a time that GCM Core is a complete replacement.
35+
36+
### Q: Does this mean the Java-based GCM for Mac/Linux is deprecated?
37+
38+
Yes. Usage of Git Credential Manager for Mac and Linux (Java GCM) should be replaced with SSH keys. If you wish to take part in the public preview of GCM Core on macOS please feel free to install the latest preview release and give feedback! Otherwise, using SSH would be prefered on macOS and Linux to Java GCM.
39+
40+
SSH configuration instructions:
41+
42+
- [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops)
43+
- [GitHub](https://help.github.com/en/articles/connecting-to-github-with-ssh)
44+
- [BitBucket](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html)
45+
46+
### Q: Why did you not just port the existing GCM Windows codebase from .NET Framework to .NET Core?
47+
48+
GCM Windows was not designed a with cross-platform architecture.
49+
50+
### What level of support does GCM Core have during the public preview?
51+
52+
Support will be best-effort. We would really appreciate your feedback as we work to make this a great experience across each platform we support. However, for mission critical applications, please use GCM for Windows on Windows or SSH on Mac and Linux.
53+
54+
### Q: Why does GCM Core not support operating system/distribution 'X', or Git hosting provider 'Y'?
55+
56+
The likely answer is we haven't gotten around to that yet! 🙂
57+
58+
We are working on ensuring support for the Windows, macOS, and Ubuntu operating system, as well as the following Git hosting providers: Azure Repos, Azure DevOps Server (TFS), GitHub, and BitBucket.
59+
60+
We are happy to accept proposals and/or contributions to enable GCM Core to run on other platforms and Git host providers. Thank you!

‎docs/usage.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Command-line usage
2+
3+
After installation, Git will use Git Credential Manager Core and you will only need to interact with any authentication dialogs asking for credentials.
4+
GCM Core stays invisible as much as possible, so ideally you’ll forget that you’re depending on GCM at all.
5+
6+
Assuming GCM Core has been installed, use your favorite terminal to execute the following commands to interact directly with GCM.
7+
8+
```shell
9+
git credential-manager [<command> [<args>]]
10+
```
11+
12+
## Commands
13+
14+
### version
15+
16+
Displays the current version.
17+
18+
### get / store / erase
19+
20+
Commands for interaction with Git. You shouldn't need to run these manually.

0 commit comments

Comments
 (0)