[Improvement] New Codespaces article: "Troubleshooting authentication to a repository" (#37059)

Co-authored-by: John Keech <jokeech@microsoft.com>
Co-authored-by: Jules <19994093+jules-p@users.noreply.github.com>

content/codespaces/developing-in-codespaces/using-source-control-in-your-codespace.md

@@ -42,6 +42,12 @@ A typical workflow for updating a file using {% data variables.product.prodname_
 * Commit the change.
 * Raise a pull request.
 
+{% note %}
+
+**Note:** By default, {% data variables.product.prodname_github_codespaces %} uses the HTTPS protocol to transfer data to and from a remote repository, and authenticates with a `GITHUB_TOKEN` configured with read and write access to the repository from which you create the codespace. If you're having issues with authentication, see "[AUTOTITLE](/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository)."
+
+{% endnote %}
+
 ## About automatic forking
 
 If you only have read access to a repository, you can usually create a codespace for the repository as long as you can fork it.

content/codespaces/troubleshooting/index.md

@@ -16,6 +16,7 @@ children:
   - /troubleshooting-included-usage
   - /exporting-changes-to-a-branch
   - /troubleshooting-creation-and-deletion-of-codespaces
+  - /troubleshooting-authentication-to-a-repository
   - /troubleshooting-your-connection-to-github-codespaces
   - /troubleshooting-prebuilds
   - /troubleshooting-personalization-for-codespaces

content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md

@@ -0,0 +1,67 @@
+---
+title: Troubleshooting authentication to a repository
+intro: Learn how to troubleshoot common authentication issues when you clone, push to, or pull from a repository in a codespace.
+versions:
+  fpt: '*'
+  ghec: '*'
+type: reference
+topics:
+  - Codespaces
+shortTitle: Authenticating to repos
+---
+
+When you create a codespace for a repository, you can generally use `git pull` and `git push` to pull and push changes to that repository without any additional authentication. However, occasionally you may see authentication errors when trying to run these operations.
+
+You may also get errors if you are trying to interact with a repository other than the one from which you created the codespace.
+
+## Authenticating to the repository you created the codespace from
+
+If you're trying to push to or pull from the repository from which you created the codespace, but authentication is failing, you may see an error like `git@github.com: Permission denied (publickey)` or `Host key verification failed`.
+
+You may see these errors if you use a dotfiles repository with {% data variables.product.prodname_github_codespaces %}, and you have configured Git to use a protocol other than HTTPS for transferring data to the remote repository. For example, you may have configured Git to use SSH by including lines like the following in a config file in your dotfiles.
+
+```
+[url "git@github.com:"]
+  insteadOf = https://github.com/
+```
+
+{% data variables.product.prodname_github_codespaces %} uses the HTTPS protocol by default, and authenticates with a `GITHUB_TOKEN` configured with read and write access to the repository from which you created the codespace. We recommend you use the default HTTPS and `GITHUB_TOKEN` in your codespace. The permissions of the `GITHUB_TOKEN` are usually limited to just one repository, following the security principle of least privilege. SSH authentication does not have fine-grained repository permissions, so an accidental exposure of your SSH key could give someone access to all your repositories.
+
+To use the default HTTPS, remove the conflicting configuration from your dotfiles. If your dotfiles repository contains an installation script in a recognized file such as `install.sh`, you can use logic like the following to exclude the configuration in codespaces.
+
+```shell
+if [ -z "$CODESPACES" ]; then
+  git config --global url."git@github.com".insteadOf "https://github.com"
+fi
+```
+
+If you're working in a codespace created from a repository you trust, and you need to use SSH, ensure that your codespace is set up to authenticate with an SSH key that is linked to your {% data variables.product.prodname_dotcom %} account. For more information, see "[AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)."
+
+## Authenticating to repositories that you didn't create the codespace from
+
+The `GITHUB_TOKEN` in a codespace is configured with read and write access to the repository from which you created the codespace. By default, the token does not have access to other repositories. You may find you cannot clone a repository, or you cannot push to a repository you have cloned.
+
+We do not recommend manually updating the value of the `GITHUB_TOKEN` in a codespace. If your project requires additional access to other repositories, we recommend you give access to these repositories in your dev container configuration. For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces)."
+
+If you need access to another repository, but don't want to update the dev container configuration, you can create a {% data variables.product.pat_generic %} with access to the repository and add the token to your codespace. We recommend you limit the token's access by using a {% data variables.product.pat_v2 %}, selecting only the repositories to which you need access, and giving the required access to the **Contents** permission only. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)."
+
+You can then add the token as an environment variable in a codespace, or as an encrypted secret for {% data variables.product.prodname_github_codespaces %}. If you create an encrypted secret, you should only allow certain trusted repositories to access the secret. When you add a new encrypted secret, you will be prompted to reload your existing codespace to pull in the new secret. For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
+
+To use the token to authenticate in your codespace, you have the following options.
+
+- When you create the environment variable or encrypted secret, you can use the name `GH_TOKEN`. The `GH_TOKEN` variable is used by default in {% data variables.product.prodname_cli %} operations, so you can clone the repository using the command `gh repo clone OWNER/REPO`. 
+
+  However, if you then try to push to the repository using `git push`, Git's credential helper will try to use the existing `GITHUB_TOKEN` to authenticate, and authentication will fail. You can override the helper, but this may introduce friction when you try to interact with the original repository from which you created the codespace. 
+- You can clone the repository with a URL that includes the access token. Replace `YOUR-VARIABLE` with the name of the environment variable or encrypted secret you created.
+
+  ```shell
+  git clone https://PAT:$YOUR-VARIABLE@github.com/OWNER/REPO`
+  ```
+
+  This will store the access token for the specific repository, so you will be able to push to and pull from the repository without overriding the existing credential helper. 
+  
+  {% note %}
+
+  **Note:** If you clone in this way, the token will be visible in your Git configuration. You should only use this method when working in a codespace created from a repository you trust, and you should limit the scope of the access token as much as possible.
+
+  {% endnote %}

content/codespaces/troubleshooting/troubleshooting-personalization-for-codespaces.md

@@ -28,7 +28,9 @@ If your codespace fails to pick up configuration settings from dotfiles, you sho
    - If your dotfiles were not cloned, check `/workspaces/.codespaces/.persistedshare/EnvironmentLog.txt` to see if there was a problem cloning them.
 1. Check `/workspaces/.codespaces/.persistedshare/creation.log` for possible issues. For more information, see [Creation logs](/codespaces/troubleshooting/github-codespaces-logs#creation-logs).
 
-If the configuration from your dotfiles is correctly picked up, but part of the configuration is incompatible with codespaces, use the `$CODESPACES` environment variable to add conditional logic for codespace-specific configuration settings.
+If the configuration from your dotfiles is correctly picked up, but part of the configuration is incompatible with codespaces, use the `$CODESPACES` environment variable to add conditional logic for codespace-specific configuration settings. For more information about configuration that may be incompatible with codespaces, see:
+- "[AUTOTITLE](/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository#problems-with-the-repository-from-which-you-created-the-codespace)"
+- "[AUTOTITLE](/codespaces/troubleshooting/troubleshooting-gpg-verification-for-github-codespaces#errors-caused-by-conflicting-configuration)"
 
 ## Troubleshooting Settings Sync