From 23c513ce8af9b69168a325928ca064f35cc4dbcb Mon Sep 17 00:00:00 2001 From: Jim DeLaHunt Date: Mon, 23 Sep 2024 22:04:10 -0700 Subject: [PATCH 1/4] Improve caching-your-github-credentials-in-git.md based on my confusion 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. --- .../caching-your-github-credentials-in-git.md | 23 ++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md index 427928e2cf20..05180fcdb5b6 100644 --- a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md +++ b/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.' versions: fpt: '*' ghes: '*' @@ -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. 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. @@ -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). {% mac %} @@ -105,3 +105,20 @@ For more options for storing your credentials on Linux, see [Credential Storage]
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 + +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 you must take an extra step. You must [request that organization's approval for OAuth access by your helper](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps), and the [organization must approve access](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization). 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. + +{% tip %} + +**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: + +``` +remote: Repository not found. +fatal: repository 'https://github.com/ExampleUser/example-repo.git/' not found +``` + +{% endtip %} From bf3c23988d985fe33a3f5b2fad3717ded5b4c7e2 Mon Sep 17 00:00:00 2001 From: Jim DeLaHunt Date: Mon, 23 Sep 2024 22:34:51 -0700 Subject: [PATCH 2/4] Lint and style improvements to caching-your-github-credentials-in-git.md 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. --- .../caching-your-github-credentials-in-git.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md index 05180fcdb5b6..be4ce2e18096 100644 --- a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md +++ b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md @@ -110,13 +110,18 @@ For more information or to report issues with GCM, see the official GCM docs at 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 you must take an extra step. You must [request that organization's approval for OAuth access by your helper](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps), and the [organization must approve access](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization). 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. +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)". +2. The [organization must approve access. See "[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)". + +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. {% tip %} -**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: +**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: -``` +```text remote: Repository not found. fatal: repository 'https://github.com/ExampleUser/example-repo.git/' not found ``` From fab568c7f527af1c3e1b30e9b66e7ccba1dbd430 Mon Sep 17 00:00:00 2001 From: Jim DeLaHunt Date: Mon, 23 Sep 2024 22:59:00 -0700 Subject: [PATCH 3/4] Fix lint problems in caching-your-github-credentials-in-git.md 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. --- .../caching-your-github-credentials-in-git.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md index be4ce2e18096..9dd71d212143 100644 --- a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md +++ b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md @@ -113,7 +113,7 @@ There are [many Git credential helpers](https://git-scm.com/doc/credential-helpe 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)". -2. The [organization must approve access. See "[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)". +2. The organization must approve access. See "[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)". 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. @@ -123,7 +123,7 @@ Access is pre-authorized for {% data variables.product.prodname_cli %} and Git C ```text remote: Repository not found. -fatal: repository 'https://github.com/ExampleUser/example-repo.git/' not found +fatal: repository 'https://github.com/User/repo.git/' not found ``` {% endtip %} From c9af082ba5ccb32e02fb2af469165a4b9fbd5def Mon Sep 17 00:00:00 2001 From: Jim DeLaHunt Date: Mon, 23 Sep 2024 23:04:59 -0700 Subject: [PATCH 4/4] Fix OL numbering in caching-your-github-credentials-in-git.md 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". --- .../caching-your-github-credentials-in-git.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md index 9dd71d212143..f710625251a9 100644 --- a/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md +++ b/content/get-started/getting-started-with-git/caching-your-github-credentials-in-git.md @@ -113,7 +113,7 @@ There are [many Git credential helpers](https://git-scm.com/doc/credential-helpe 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)". -2. The organization must approve access. See "[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)". +1. The organization must approve access. See "[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)". 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.