From 70acabc132dfed206b4ea78c3ba05584c760f6ea Mon Sep 17 00:00:00 2001
From: Andy Feller <andyfeller@github.com>
Date: Thu, 9 May 2024 08:27:58 -0400
Subject: [PATCH] Creating doc to capture Codespace usage guidance

---
 docs/codespaces.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 docs/codespaces.md

diff --git a/docs/codespaces.md b/docs/codespaces.md
new file mode 100644
index 000000000..842b37e4c
--- /dev/null
+++ b/docs/codespaces.md
@@ -0,0 +1,36 @@
+# Guide to working with Codespaces using the CLI
+
+For more information on Codespaces, see [Codespaces section in GitHub Docs](https://docs.github.com/en/codespaces).
+
+## Access to other repositories
+
+The codespace creation process will prompt you to review and authorize additional permissions defined in
+`devcontainer.json` at creation time:
+
+```json
+{
+  "customizations": {
+    "codespaces": {
+      "repositories": {
+        "my_org/my_repo": {
+          "permissions": {
+            "issues": "write"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+However, any changes to `codespaces` customizations will not be re-evaluated for an existing
+codespace.  This requires you to create a new codespace in order to authorize the new
+permissions using `gh codespace create`.
+
+For more information, see ["Repository access"](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces).
+
+If additional access is needed for an existing codespace or access to a repository outside of
+your user or organization account, the use of a fine-grained personal access token as an
+environment variable or Codespaces secret might be considered.
+
+For more information, see ["Authenticating to repositories"](https://docs.github.com/en/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository).