doc: add information about the forge package

1 files changed, 30 insertions, 0 deletions

diff --git a/README.org b/README.org
index 2433a1d..cdbe67f 100644
--- a/README.org
+++ b/README.org
@@ -31,3 +31,33 @@ If the program you debug needs argument, call =M-x dap-debug-edit-template=. Add
 The binding =C-c d= will bring an hydra menu for debugging.
 
 The REPL is not brought on by default when starting a debugging session, but =M-x dap-ui-repl= will start a REPL (the position is controlled by the variable =dap-ui-buffer-configurations=).
+** git
+*** forge
+The [[https://github.com/magit/forge][forge]] package helps managing git repositories that are part of a forge. The interaction with the forges is done through the forge's API. By default, GitHub is already configured, but for additional forges, we need some custom setup.
+
+First, we need to add the new forge to the list:
+#+begin_src elisp
+(with-eval-after-load 'forge
+  (push '("github.rbxs.com" "github.rbx.com/api/v3"
+          "github.rbx.com" forge-github-repository)
+        forge-alist))
+#+end_src
+
+Next, we need a token for the API:
+- https://github.com/settings/tokens
+- https://github.rbx.com/settings/tokens
+
+The tokens need the following access:
+- repo:*
+- user:*
+- admin:read:org
+
+The tokens need to be stored in =~./authinfo.gpg=, with the following format:
+#+begin_src
+machine api.github.com login fcuny-rbx^forge password <TOKEN>
+machine github.rbx.com/api/v3 login fcuny^forge password <TOKEN>
+#+end_src
+
+When pulling topics for a repository, by default, we're going to be prompted for the username to use for the API. The username can be set in the git configuration with =github.github.rbx.com/api/v3.user= (for github.rbx.com). This can be set per repository (with =git config github.github.rbx.com/api/v3.user fcuny=) or globally (with =git config --global github.github.rbx.com/api/v3.user fcuny=).
+
+To use the forge, get in a =magit= buffer, then hit =N=, which will present a transiant menue. From here, select the action you want.