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

JDLH · 2024-09-24T05:42:54Z

Why:

This is based on my difficulties understanding how to get OAuth authentication from my local Git installation. The current content does not mention OAuth, or the need for organisation approval of OAuth apps not pre-approved by GitHub. Both those omissions caused obstacles for me. This is the content I wished I had at the time.

What's being changed (if available, include any code snippets, screenshots, or gifs):

Adding section about other Git credential helpers, and mention OAuth. Add a few words putting GitHub CLI and GCM in relationship to the local Git installation.

I had an earlier version of this PR, #34711 , but I inadvertently closed it. Oops. This replaces that PR. It also addresses some lint problems.

Check off the following:

I have reviewed my changes in staging, available via the View deployment link in this PR's timeline (this link will be available after opening the PR).
- For content changes, you will also see an automatically generated comment with links directly to pages you've modified. The comment won't appear if your PR only edits files in the data directory.
For content changes, I have completed the self-review checklist.

Adding section about other Git credential helpers, and mention OAuth. This is based on my difficulties understanding how to get OAuth authentication from my local Git installation. The current content does not mention OAuth, or the need for organisation approval of OAuth apps not pre-approved by GitHub. Both those omissions caused obstacles for me. This is the content I wished I had at the time.

Formatting changes to correct lint problems. Label a code fence as text. Remove docs.github.com from links to docs. Delete a traling space. Turn a long sentence with two inline links into a 2-item list. This responds in part to "Writing for translation" style instructions.

github-actions · 2024-09-24T05:46:49Z

Automatically generated comment ℹ️

This comment is automatically generated and will be overwritten every time changes are committed to this branch.

The table contains an overview of files in the content directory that have been changed in this pull request. It's provided to make it easy to review your changes on the staging site. Please note that changes to the data directory will not show up in this table.

Content directory changes

You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request.

Source	Preview	Production	What Changed
`get-started/getting-started-with-git/caching-your-github-credentials-in-git.md`	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10

fpt: Free, Pro, Team
ghec: GitHub Enterprise Cloud
ghes: GitHub Enterprise Server

Removed spurious left square bracket in line 116, to attempt a fix to lint problem "MD029, ol-prefix Ordered list item prefix". Shortened line 126, a text error message. It is now 64 characters. Still longer than the desired 60 characters, but I don't see how to make it 4 characters shorter and still keep the example understandable. So, I expect it will still get a lint warning. Links on lines 115 and 116 are unchanged. The link checker seems to have a problem with them, and I don't know how to fix it.

Fix a lint problem in line 116. Change number of second item in the ordered list from "2" to "1". I am guessing that every item in the list should be numbered "1".

JDLH · 2024-09-24T06:18:17Z

I would like help diagnosing these check-links errors:

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

The source text from caching-your-github-credentials-in-git.md?plain=1#L115-L116 is:

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

The public URLs of the articles to which I want to link are:

I understand from another link checker run that I should not include the https://docs.github.com/ prefix in the link. Fair enough.

I don't understand the correct way to express those links in this article. I would appreciate guidance.

The output from test-changed-content looks to me like a consequence of the same link problem. The error message says, "Error: Unable to find Page by…" and gives the same link paths.

JDLH · 2024-09-24T06:23:54Z

I would like help diagnosing these check-links errors:

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

Interestingly, the fpt and ghec previews listed above have correct links to the GitHub articles in question. The ghes previews all give me error messages, however.

github-actions · 2024-09-24T14:33:26Z

Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert 👀

nguyenalex836 · 2024-09-24T14:33:27Z

@JDLH Thanks so much for opening a PR! I'll get this triaged for review ✨

subatoi · 2024-09-24T17:32:25Z

content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

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


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

JDLH · 2024-10-13T09:29:23Z

@Jaswanthgowda when you say, "Please check the settings of my account", I don't know how your request relates to this pull request. This is about improving the GitHub documentation. If you are new to GitHub and want help, perhaps try GitHub's "Get started" instructions.

andyfeller

Wanting to chime in as one of the engineers on the GitHub CLI but also as a former services engineer, I'm somewhat concerned with the suggested documentation and language changes because they could be misleading to certain readers with regard to how these various tools are used by git and what GitHub supports.

Users configure git to use the GitHub CLI, GCM, or whatever tool they desire as a credential helper. When git is invoked and needs credentials, it will call whatever tools is configured to provide a relevant credential.

For example, here is git configured to call gh for a credential when needed when working with a git remote for github.com:

credential.https://github.com.helper=
credential.https://github.com.helper=!/opt/homebrew/bin/gh auth git-credential

cc: @nguyenalex836

andyfeller · 2024-10-16T22:50:53Z

content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

@@ -7,7 +7,7 @@ redirect_from:
  - /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.'


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

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

andyfeller · 2024-10-16T22:52:42Z

content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

@@ -23,7 +23,7 @@ shortTitle: Caching credentials

 ## {% 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.


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

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.

andyfeller · 2024-10-16T22:54:45Z

content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

@@ -34,7 +34,7 @@ For more information about authenticating with {% data variables.product.prodnam

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


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

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.

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.

andyfeller · 2024-10-16T22:55:57Z

content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md

@@ -105,3 +105,25 @@ For more options for storing your credentials on Linux, see [Credential Storage]
 <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


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.

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

nguyenalex836 · 2024-10-18T16:08:14Z

@JDLH Thank you again for opening this PR, and raising a flag on this topic! ✨ We agree the need for clarity in this portion of the docs, but given all the nuances on this topic, we'll need to handle this internally 💛

If you're looking for another issue to pick up, take a look at our help wanted section to find open issues you can work on ✨

JDLH · 2024-10-20T18:12:30Z

@nguyenalex836 thank you for considering this PR, and I understand that GitHub will want to consider this part of the docs internally rather than building off this PR. Fair enough. However, I will take the liberty of adding some closing replies. I hope they will help you as you improve the docs internally.

@andyfeller thank you for the review. I see your points. Some of them seem to refer to pre-existing content in the docs, rather than my proposed changes. Also, there are places where I think GitHub could be clearer about the difference between, "this is what GitHub recommends" and "this is the only thing GitHub will allow". I have added replies where I think this is the case.

JDLH added 2 commits September 23, 2024 22:04

github-actions bot added the triage Do not begin working on this issue until triaged by the team label Sep 24, 2024

JDLH added 2 commits September 23, 2024 22:59

Fix OL numbering in caching-your-github-credentials-in-git.md

c9af082

Fix a lint problem in line 116. Change number of second item in the ordered list from "2" to "1". I am guessing that every item in the list should be numbered "1".

JDLH mentioned this pull request Sep 24, 2024

Clarify use of OAuth credential helpers in local Git installation #34710

Open

1 task

JDLH mentioned this pull request Sep 24, 2024

Problem with GitHub organization hickford/git-credential-oauth#63

Closed

subatoi reviewed Sep 24, 2024

View reviewed changes

This comment was marked as off-topic.

Sign in to view

andyfeller reviewed Oct 16, 2024

View reviewed changes

nguyenalex836 closed this Oct 18, 2024

nguyenalex836 added SME reviewed An SME has reviewed this issue/PR and removed waiting for review Issue/PR is waiting for a writer's review needs SME This proposal needs review from a subject matter expert labels Oct 18, 2024

This comment was marked as spam.

Sign in to view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

JDLH commented Sep 24, 2024

github-actions bot commented Sep 24, 2024 •

edited

Loading

JDLH commented Sep 24, 2024

JDLH commented Sep 24, 2024

github-actions bot commented Sep 24, 2024

nguyenalex836 commented Sep 24, 2024

subatoi Sep 24, 2024

This comment was marked as off-topic.

JDLH commented Oct 13, 2024 •

edited

Loading

andyfeller left a comment •

edited

Loading

andyfeller Oct 16, 2024

JDLH Oct 20, 2024

andyfeller Oct 16, 2024

JDLH Oct 20, 2024

andyfeller Oct 16, 2024

williammartin Oct 17, 2024

JDLH Oct 20, 2024

andyfeller Oct 16, 2024

JDLH Oct 20, 2024

nguyenalex836 commented Oct 18, 2024

This comment was marked as spam.

JDLH commented Oct 20, 2024

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

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

Conversation

JDLH commented Sep 24, 2024

Why:

What's being changed (if available, include any code snippets, screenshots, or gifs):

Check off the following:

github-actions bot commented Sep 24, 2024 • edited Loading

Automatically generated comment ℹ️

Content directory changes

JDLH commented Sep 24, 2024

JDLH commented Sep 24, 2024

github-actions bot commented Sep 24, 2024

nguyenalex836 commented Sep 24, 2024

Choose a reason for hiding this comment

This comment was marked as off-topic.

JDLH commented Oct 13, 2024 • edited Loading

andyfeller left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nguyenalex836 commented Oct 18, 2024

This comment was marked as spam.

JDLH commented Oct 20, 2024

github-actions bot commented Sep 24, 2024 •

edited

Loading

JDLH commented Oct 13, 2024 •

edited

Loading

andyfeller left a comment •

edited

Loading