Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Patch for #34710, improving caching credentials with oauth mention #34712

Closed
wants to merge 4 commits into from
Closed

Patch for #34710, improving caching credentials with oauth mention #34712

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
23c513c
Improve caching-your-github-credentials-in-git.md based on my confusion
JDLH Sep 24, 2024
bf3c239
Lint and style improvements to caching-your-github-credentials-in-gi…
JDLH Sep 24, 2024
fab568c
Fix lint problems in caching-your-github-credentials-in-git.md
JDLH Sep 24, 2024
c9af082
Fix OL numbering in caching-your-github-credentials-in-git.md
JDLH Sep 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 25 additions & 3 deletions .../get-started/getting-started-with-git/caching-your-github-credentials-in-git.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
- /github/using-git/caching-your-github-credentials-in-git
- /github/getting-started-with-github/caching-your-github-credentials-in-git
- /github/getting-started-with-github/getting-started-with-git/caching-your-github-credentials-in-git
intro: 'If you''re [cloning {% data variables.product.product_name %} repositories using HTTPS](/github/getting-started-with-github/about-remote-repositories), we recommend you use {% data variables.product.prodname_cli %} or Git Credential Manager (GCM) to remember your credentials.'
intro: 'If you''re [cloning {% data variables.product.product_name %} repositories using HTTPS](/github/getting-started-with-github/about-remote-repositories), we recommend you use {% data variables.product.prodname_cli %} or a Git credential helper to authenticate and to remember your credentials.'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hesitate making this any generic git credential manager as GitHub specifically supports GCM, which is the specific recommendation.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest that the docs should describe both what is possible, and what is recommended. The previous wording suggests that GCM is the only possible credential helper usable. I think that is inaccurate; clearly GitHub has a way of allowing other OAuth-based credential helpers. My wording suggestion is focussed on being more inclusive about what is possible. Maybe add a sentence about what is recommended (though the later paragraphs talk about that).

versions:
fpt: '*'
ghes: '*'
Expand All @@ -23,7 +23,7 @@

## {% data variables.product.prodname_cli %}

{% data variables.product.prodname_cli %} will automatically store your Git credentials for you when you choose `HTTPS` as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.product_name %} credentials.
{% data variables.product.prodname_cli %} works cooperatively with Git on your command line. It helps you log in to {% data variables.product.product_name %}, and automatically stores your Git credentials for you. Choose `HTTPS` as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.product_name %} credentials.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically, users can configure git to leverage the GitHub CLI as a credential manager, retrieving the OAuth token stored within the OS-specific secret manager whenever git is called via gh commands.

I hesitate with this language because it is somewhat misleading and technically the credential being stored isn't solely or primarily for working with git but working with GitHub. 🤔

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that the wording "store your Git credentials for you" is in the current docs. If this is misleading, and should instead read, "store your GitHub credentials for you", or "GitHub OAuth token" if you prefer, then that is something to consider fixing in the current docs independent of this PR.


1. [Install](https://github.com/cli/cli#installation) {% data variables.product.prodname_cli %} on macOS, Windows, or Linux.
1. In the command line, enter `gh auth login`, then follow the prompts.
Expand All @@ -34,7 +34,7 @@

## Git Credential Manager

[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) is another way to store your credentials securely and connect to GitHub over HTTPS. With GCM, you don't have to manually [create and store a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), as GCM manages authentication on your behalf, including 2FA (two-factor authentication).
[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) extends your Git installation. On Git's behalf, it helps you log in to {% data variables.product.product_name %}, including 2FA (two-factor authentication), and stores your credentials securely. Or, if you have manually [created and stored a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), GCM can store that token securely, and provided it to {% data variables.product.product_name %} automatically when needed. In Git terms, GCM is an [OAuth credential helper](https://git-scm.com/docs/gitcredentials).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, I think the language here is a little misleading:

  • GCM is a git credential manager that can be used with GitHub or other git platforms
  • Because of this, GCM isn't storing OAuth credentials, but storing credentials used with git
  • The "GCM can store that token securely" implies or infers that users could insecurely store credentials in GCM, which I don't know is true and might be misleading

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the thing that's tripping up around OAuth is that gh and gcm can both act as oauth credential helpers. Andy's right that the credential helpers store whatever credential is used to authenticate git. Optionally, some credential helpers can perform an OAuth flow for you to obtain a token so that you don't need to create one yourself.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The topic of this part of the docs is Caching your GitHub credentials in Git, as part of Getting started with Git. I think the existing docs don't explain well enough the three points @andyfeller lists about how credentials, GitHub, and git interact. They instead tell users how to set up one mechanism works.

Both explaining and instructing "how to" are valid goals for documentation, but they are not the same thing. See the Diátaxis framework for what I think is a pretty good explanation of the difference.

The purpose of my PR was essentially to improve the explanation aspect of this page of the docs. I sense that the pushback relates to keeping this page a "how to". GitHub should make a choice about what the goal of this page is.


{% mac %}

Expand Down Expand Up @@ -105,3 +105,25 @@
<br>

For more information or to report issues with GCM, see the official GCM docs at "[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager)."

## Other Git credential helpers
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I cannot speak for this section here but I hesitate whether GitHub officially supports these other git credential helpers. Again, the 2 main credential helps I've seen supported are the GitHub CLI and GCM. I don't think GitHub needs to be an authority on all git credential helpers nor do I think we support everything.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@andyfeller, it is certainly helpful for GitHub to define which helpers are recommended. I argue that it is important for this page to be clear about whether other credential helpers are allowed.

The fact that GitHub has a mechanism for detecting OAuth apps other than GitHub CLI and GCM, and docs on Approving OAuth apps for your organization, gives me the message that other credential helpers are allowed. If they are allowed, then I think the docs should say that somewhere, rather than be silent.


There are [many Git credential helpers](https://git-scm.com/doc/credential-helpers). Those which can authenticate via OAuth might well serve to authenticate to Git with your {% data variables.product.product_name %} credentials. Note that a Git installation can work with multiple credential helpers — it tries each in turn, until one gets it access. Thus you can perhaps add a credential helper for {% data variables.product.product_name %} to your existing helpers. Follow the instructions for the helper, and the [Git credentials documentation](https://git-scm.com/docs/gitcredentials), to configure the helper.

OAuth credential helpers will get you immediate access to your own repos. If you work with repos controlled by an organization, or with your forks and clones of those repos, then two extra steps are necessary.

1. You must request that organization's approval for OAuth access by your helper. See "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps)".
1. The organization must approve access. See "[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)".
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @JDLH — the inclusion of any links to articles such as this one, which is not versioned for GHES, in an article that is versioned for GHES, will cause link errors.

We'd look at fixing these once an SME has looked at the content you're proposing.

Many thanks


Check failure on line 117 in content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

View workflow job for this annotation

GitHub Actions / test-changed-content

Error 

Unable to find Page by '/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps'.
    To fix it, look at content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md on line 117 and see if the link is correct and active.
Access is pre-authorized for {% data variables.product.prodname_cli %} and Git Credential Manager. If you use those tools, you do not need to request approval.

Check failure on line 118 in content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

View workflow job for this annotation

GitHub Actions / test-changed-content

Error 

Unable to find Page by '/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization'.
    To fix it, look at content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md on line 118 and see if the link is correct and active.

{% tip %}

Check failure on line 121 in content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

View workflow job for this annotation

GitHub Actions / check-links

Error 

Unable to find Page by '/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps'.
    To fix it, look at content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md on line 121 and see if the link is correct and active.
**Tip:** If you use a Git command which requires access to an organization's repo (e.g. `git fetch`), and your helper seems to authenticate correctly, but the command fails with an error, then check that you have received the organization's approval for OAuth access by that app. The error may say something like:

Check failure on line 122 in content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

View workflow job for this annotation

GitHub Actions / check-links

Error 

Unable to find Page by '/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization'.
    To fix it, look at content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md on line 122 and see if the link is correct and active.

```text
remote: Repository not found.
fatal: repository 'https://github.com/User/repo.git/' not found
```

{% endtip %}
Loading