Public SOP: connecting VS Code to Codebox Go

2026-08-20 09:28:48 +00:00
commit e52d4c56de
1 changed files with 172 additions and 0 deletions
@@ -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.