Public SOP: connecting VS Code to Codebox Go

Home.md

@@ -0,0 +1,172 @@
+# Connecting VS Code to Codebox Go
+
+Codebox Go is our self-hosted Git service. This guide gets you from a fresh
+machine to working in VS Code, and explains the handful of things that
+commonly go wrong.
+
+The address is the same wherever you are:
+
+```
+https://git.hoppe.mywire.org
+```
+
+Use it from home, from a laptop elsewhere, from anything. If you were given a
+different address at some point, prefer this one — a link that only works on
+one network will strand you the moment you move.
+
+---
+
+## Which kind of account do you have?
+
+|  | Team member | External collaborator |
+| --- | --- | --- |
+| Sign-in | Your organisation account | An account created for you, with its own password |
+| Set-up | One script does everything | Clone the specific repository you were given |
+| You will see | The repositories your team has | Usually one repository |
+
+Both sign in at the same address and both work the same way in VS Code. The
+difference is only how many repositories you can see.
+
+---
+
+## First: sign in on the web
+
+Go to the address above and sign in **before** touching VS Code. It confirms
+your account works and tells you immediately which repositories you have.
+
+If sign-in fails, skip to [Sign-in is rejected](#sign-in-is-rejected).
+
+---
+
+## Team members: one script
+
+Members can clone the `workspace` repository, which contains a `bootstrap`
+script. It asks the server which repositories **your** account can see, clones
+exactly those, and writes a VS Code workspace file containing them.
+
+```powershell
+git clone https://git.hoppe.mywire.org/Hoppe.home/workspace.git
+cd workspace
+.\bootstrap.ps1
+```
+
+Then open the workspace file it prints at the end.
+
+Inside VS Code you can instead press **Ctrl+Shift+P**, choose **Tasks: Run
+Task**, then **Set up my Codebox Go workspace**.
+
+Re-run it whenever you like. It updates what you already have, adds anything
+newly shared with you, and rewrites the workspace file — so it doubles as a
+way to check you have not missed a repository.
+
+There is no fixed list of repositories in the script, deliberately. It asks
+the server every time, so it can never offer you something you are not allowed
+to clone, and it cannot go stale.
+
+## External collaborators: clone your repository
+
+You will normally have exactly one. Clone it directly:
+
+```
+git clone https://git.hoppe.mywire.org/<owner>/<repository>.git
+```
+
+Or in VS Code: **Ctrl+Shift+P** → **Git: Clone** → paste the URL.
+
+When prompted, enter your username and password. Choose a folder that is
+**not** inside OneDrive or another syncing folder — see below for why.
+
+---
+
+## Passwords and tokens
+
+You can sign in with your password. You can also create a **personal access
+token** under **Settings → Applications**, and use it anywhere a password is
+asked for.
+
+A token is the better choice on a laptop, a shared machine, or anything you
+carry around: it can be revoked on its own without changing your password, and
+you can issue a separate one per device.
+
+Never commit a token to a repository, and never paste one into an issue or a
+chat message. If one leaks, revoke it in the same place you created it.
+
+---
+
+## Things that commonly go wrong
+
+### I can only see a few repositories
+
+This is almost always your access, not a fault. Repositories you have not been
+given are hidden rather than shown as forbidden, so a short list looks
+identical to a broken sign-in.
+
+Ask for the repository you need, naming it. Nothing on your machine will fix
+it.
+
+### The clone hangs, or keeps asking for a username
+
+If a prompt appears for an address different from the one you cloned from,
+that is the cause. Credentials are stored per address, so a request to a
+second address finds nothing saved and waits for input — which looks like a
+stalled download rather than a question.
+
+Cancel, and clone using the address at the top of this page. If your system
+has stored something unhelpful, clear the saved entry (on Windows: Credential
+Manager → Windows Credentials) and let it ask again.
+
+### "Your connection is not private" / certificate error
+
+Check your device's **date and time** first. A certificate is only valid
+between two dates, so a clock that is wrong by days makes a perfectly good
+certificate look invalid. This is by far the most common cause.
+
+On Windows: **Settings → Time & language → Date & time**, turn on **Set time
+automatically**, then **Sync now**. If the clock keeps resetting after every
+restart, the machine's internal battery is likely flat.
+
+A wrong clock also breaks sign-ins on many other services, so fixing it tends
+to clear up more than this one error.
+
+### It worked at home but not elsewhere
+
+Your repository is pointing at an address that only exists on the home
+network. Point it at the public one:
+
+```
+git remote set-url origin https://git.hoppe.mywire.org/<owner>/<repository>.git
+```
+
+Check what it is currently using with `git remote -v`.
+
+### Strange failures inside OneDrive
+
+Do not clone into OneDrive, Dropbox, Google Drive or iCloud Drive. Sync copies
+files while Git is still writing them, which produces stalls, lock errors and
+apparent corruption that look like network problems.
+
+Use a plain local folder such as `C:\Users\<you>\Code`. The bootstrap script
+refuses a syncing folder for this reason.
+
+### Sign-in is rejected
+
+- Check whether you are entering the right kind of credential. Team members
+  use their organisation account; external collaborators use the password set
+  up for them here.
+- If you use a token, confirm it has not been revoked, and that you pasted it
+  whole.
+- Repeated failures may temporarily rate-limit you. Wait a few minutes rather
+  than retrying rapidly.
+
+---
+
+## Getting help
+
+Ask the person who gave you access. When you do, include:
+
+- what you ran or clicked,
+- the exact error text,
+- and the address it mentions.
+
+That last one resolves most cases immediately, because the wrong address is
+the single most common cause.