| 1 | --- |
| 2 | title: The desktop app |
| 3 | description: g1t in a window of its own, for Windows, macOS and Linux, with notifications from your system, a badge on the icon, g1t:// links, a runner for your workspace's jobs, and updates that install themselves. |
| 4 | --- |
| 5 | |
| 6 | The desktop app is g1t in a window of its own. Everything in it is the |
| 7 | site, [g1t.sh](https://g1t.sh), loaded live: chat, artifacts and code, |
| 8 | exactly as in a browser, so every change to g1t reaches the app the moment |
| 9 | it is deployed. What the app adds is what a browser cannot do: |
| 10 | |
| 11 | - **Notifications from your system**, for a message to you or a mention, |
| 12 | while the window is behind another. |
| 13 | - **A badge on the icon**, with what is waiting for you, and a tray icon |
| 14 | that keeps g1t running when the window is closed. |
| 15 | - **`g1t://` links**, which open a page in the app from anywhere on your |
| 16 | computer. |
| 17 | - **Updates that install themselves**, signed by g1t, in the background. |
| 18 | - **Your own g1t**, if you [run one](/guides/self-hosting/): the app points |
| 19 | at any server. |
| 20 | - **A runner for your workspace**, started with the app, so your |
| 21 | computer runs the workspace's `runs-on: self-hosted` jobs while g1t is |
| 22 | open, with nothing to install or register. See [the runner](#the-runner). |
| 23 | - **Settings of its own**: opening when you sign in to your computer, |
| 24 | what closing the window does, notifications, the badge, zoom, |
| 25 | developer tools, updates and the runner. |
| 26 | |
| 27 | Get it at [g1t.sh/download](https://g1t.sh/download), or from your account |
| 28 | menu, **Get the desktop app**. The page opens on the system you visit it |
| 29 | from, with every other platform a tab away, and lists the |
| 30 | [runner](/guides/self-hosted-runners/) and the g1t CLI for each system |
| 31 | under **Command line**. |
| 32 | |
| 33 | ## Install |
| 34 | |
| 35 | | Platform | What you get | Notes | |
| 36 | | --- | --- | --- | |
| 37 | | **Windows** 10 and 11 | An installer, `g1t-<version>-windows-x64-setup.exe` | Installs for your account alone; no administrator needed. Uses the WebView2 runtime Windows already has, and fetches it if a machine lacks it. | |
| 38 | | **macOS** 11 and later | A disk image, Apple silicon or Intel | Drag g1t to Applications. | |
| 39 | | **Linux** | An AppImage, a `.deb` or an `.rpm` | The AppImage runs anywhere once made executable (`chmod +x`). It needs WebKitGTK 4.1, which the packages install for you. | |
| 40 | |
| 41 | Every file's SHA-256 is in `SHA256SUMS` beside it, at |
| 42 | `https://g1t.sh/downloads/desktop/<version>/`. |
| 43 | |
| 44 | ### Unsigned during the alpha |
| 45 | |
| 46 | While g1t is in alpha, none of its builds are code-signed: not the desktop |
| 47 | app, the Android app, the runner or the CLI. Your system can't tell who made |
| 48 | them, so it warns you the first time you open one. Check the file against |
| 49 | its SHA-256, then: |
| 50 | |
| 51 | - **Windows**: when SmartScreen says it protected your PC, choose **More |
| 52 | info**, then **Run anyway**. |
| 53 | - **macOS**: when it says it can't check g1t, open **System Settings → |
| 54 | Privacy & Security** and choose **Open Anyway**. |
| 55 | - **Linux**: your package manager may say the `.deb` or `.rpm` isn't |
| 56 | signed. The AppImage needs only `chmod +x`. |
| 57 | |
| 58 | The app's own updates are different: each is checked against g1t's |
| 59 | signature before it installs. |
| 60 | |
| 61 | The app opens on g1t.sh's sign-in page, not the site's landing page: it |
| 62 | is for using g1t, not for reading about it. It keeps you signed in like a |
| 63 | browser does, and signing out brings you back to the sign-in page. |
| 64 | Signing in with GitHub goes to github.com and comes back inside the |
| 65 | window. |
| 66 | |
| 67 | ## Notifications and the badge |
| 68 | |
| 69 | Inside the app, the **Desktop notifications** switch in |
| 70 | [Settings → Notifications](/guides/notifications/#settings) is on and the |
| 71 | app shows them itself: while the window is behind another or hidden, a |
| 72 | message to you shows as a notification from your system, under the same |
| 73 | rules as in a browser: [what you chose to be told about](/guides/chat/#notifications), |
| 74 | never while [Do not disturb](/guides/chat/#sounds-and-do-not-disturb) is |
| 75 | on, never for a muted conversation. With the window in front, the pop-up |
| 76 | in the corner shows instead, as on the site. Clicking a notification |
| 77 | brings the app forward; opening the conversation it is about from the |
| 78 | notification is coming. |
| 79 | |
| 80 | The icon carries a badge with what is waiting for you: the count on macOS |
| 81 | and Linux, a lavender dot on Windows. The tray icon's hover text says the |
| 82 | number everywhere. With a notification, the taskbar icon flashes on |
| 83 | Windows and the dock icon bounces on macOS, while the window is not in |
| 84 | front. [The app's settings](#settings) turn off each of these: the |
| 85 | notifications, the flash and the badge. |
| 86 | |
| 87 | [Chat sounds](/guides/chat/#sounds-and-do-not-disturb) play as on the |
| 88 | site, through the app's own audio. |
| 89 | |
| 90 | ## The window and the tray |
| 91 | |
| 92 | Closing the window hides it; g1t keeps running in the tray (the menu bar |
| 93 | on macOS) so notifications still arrive. Click the tray icon, or its |
| 94 | **Open g1t**, to bring the window back; on macOS the dock icon does too. |
| 95 | **Quit g1t** in the tray menu ends it. The window remembers its size and |
| 96 | place. To have closing the window quit instead, turn off **Keep g1t |
| 97 | running when the window closes** in [the app's settings](#settings). |
| 98 | |
| 99 | The tray menu also holds **Settings…**, **Check for updates…**, **Use |
| 100 | another g1t…** and, when an update is downloaded, **Restart to update**. |
| 101 | |
| 102 | ### The title bar |
| 103 | |
| 104 | g1t draws its own title bar, so the whole window is g1t and looks the |
| 105 | same on Windows, macOS and Linux. It takes the colours of g1t's rail, in |
| 106 | light and dark. |
| 107 | |
| 108 | | Part | What it does | |
| 109 | | --- | --- | |
| 110 | | **☰** (Windows and Linux) | Opens the app's [menu](#the-menu). | |
| 111 | | **← →** | Back and forward through the pages you have been on. | |
| 112 | | **Search** | In the middle: searches your workspace, as **Ctrl+K** or **⌘K** does. Before you are signed in, it shows the page's title. | |
| 113 | | **The runner's dot** | At the right, right beside **Settings**: a small circle in the colour of what [the runner](#the-runner) is doing, live: green while it runs, blue and breathing while it works (*Running a job*, *Runner starting*, *Runner updating*), amber or red when it needs you, grey when it is stopped or off. Hover it for the words; a wide window shows them beside it. It opens [the runner menu](#the-runner-menu). | |
| 114 | | **Settings** | Opens [the settings](#settings) over the page. | |
| 115 | | **Minimize, maximize, close** (Windows and Linux) | At the right. Close keeps g1t in the tray unless [the settings](#settings) say it quits. On macOS the window's own buttons sit at the left of the bar. | |
| 116 | |
| 117 | Drag the bar to move the window, and double-click it to maximize or |
| 118 | restore it. The bar is there on every page the window shows, signing in |
| 119 | with GitHub included, and the page sits below it, never under it. |
| 120 | |
| 121 | To have the system's title bar instead, turn on **Use the system's title |
| 122 | bar** in [the settings](#settings). On Windows and Linux the menu bar |
| 123 | comes back under it. g1t restarts to change it: the settings offer |
| 124 | **Restart now**. |
| 125 | |
| 126 | ### The menu |
| 127 | |
| 128 | The app has the menus a desktop app has: under **☰** at the left of the |
| 129 | title bar on Windows and Linux, or under the system's title bar if you |
| 130 | use it, and at the top of the screen on macOS. Their shortcuts work |
| 131 | either way. |
| 132 | |
| 133 | | Menu | What is in it | |
| 134 | | --- | --- | |
| 135 | | **File** (**g1t** on macOS) | **Settings** (Ctrl+, or ⌘,), **Use another g1t…**, **Close window** (Ctrl+W), **Quit g1t** (Ctrl+Q or ⌘Q) | |
| 136 | | **Edit** | Undo, redo, cut, copy, paste and select all | |
| 137 | | **View** | **Reload** (Ctrl+R), **Actual size** (Ctrl+0), **Zoom in** (Ctrl+=), **Zoom out** (Ctrl+-), full screen, **Developer tools** (Ctrl+Shift+I, or ⌥⌘I), once [turned on](#developer-tools) | |
| 138 | | **Go** | **Back** (Alt+Left, or ⌘[), **Forward** (Alt+Right, or ⌘]), **Home**, **Notifications** | |
| 139 | | **Window** | Minimize and maximize | |
| 140 | | **Help** | **Desktop app guide** and **g1t.sh status**, in your browser; **Check for updates…**; **Restart to update**, once one is downloaded; **About g1t** | |
| 141 | |
| 142 | ## Settings |
| 143 | |
| 144 | The app's own settings open over the page you are on, with their |
| 145 | sections down the left (**Starting and closing**, **Runner**, |
| 146 | **Notifications**, **Window**, **Updates**, **Server**, **About**) and the |
| 147 | one you choose on the right. Open them with the **Settings** button at the |
| 148 | right of the title bar, **Settings** in the File menu (the g1t menu on |
| 149 | macOS) or Ctrl+, (⌘, on macOS), **Settings…** in the tray, or **Desktop |
| 150 | app settings** in your account menu on g1t; the window comes forward if it |
| 151 | was hidden. Escape or **×** closes them. Each change takes effect at once |
| 152 | and is kept on this computer; there is nothing to save. Your account's |
| 153 | settings, which things notify you among them, stay on g1t, in |
| 154 | [your settings](/guides/notifications/#settings). |
| 155 | |
| 156 | While the window shows no page of g1t's, such as the page that picks a |
| 157 | server, the page g1t shows when it can't reach the server, or signing in |
| 158 | with GitHub, the settings open in a window of their own instead, with the |
| 159 | same settings. |
| 160 | |
| 161 | | Setting | Default | What it does | |
| 162 | | --- | --- | --- | |
| 163 | | **Open g1t when you sign in** | Off | Starts g1t with your computer. The system keeps this: a login item on macOS, a startup entry on Windows, an autostart entry on Linux. | |
| 164 | | **Start in the tray** | On | Opened at sign-in, g1t waits in the tray without opening its window. Opening it yourself always shows the window. | |
| 165 | | **Keep g1t running when the window closes** | On | Closing the window leaves g1t in the tray for notifications. Off, closing the window quits. | |
| 166 | | **Show notifications** | On | Notifications from your system. Off, nothing pops up from the app, whatever your account's settings say. | |
| 167 | | **Flash the taskbar icon** (**Bounce the dock icon** on macOS) | On | Asks for your attention with a notification while the window is not in front. | |
| 168 | | **Show a badge on the icon** | On | The count, or the dot on Windows. Off, the icon stays clean; the tray's hover text still counts. | |
| 169 | | **Use the system's title bar** | Off | The system's title bar in place of [g1t's own](#the-title-bar), with the menu bar under it on Windows and Linux. Takes effect when g1t restarts. | |
| 170 | | **Zoom** | 100% | How large g1t is drawn, from 67% to 200%. The View menu changes it too. | |
| 171 | | **Developer tools** | Off | F12 or Ctrl+Shift+I (⌥⌘I on macOS), and **Developer tools** in the View menu, open the web inspector for the page. See [Developer tools](#developer-tools). | |
| 172 | | **Download updates by themselves** | On | Off, the app never checks on its own; **Check for updates** still does. The runner's updates follow it too: off, only **Check for runner updates** looks for a newer runner. | |
| 173 | |
| 174 | **Updates** also shows the app's version and whether it is up to date, |
| 175 | with **Check for updates** (see [Updates](#updates)); **Server** shows the |
| 176 | server it opens, with **Change…** to [use another g1t](#your-own-g1t); and |
| 177 | **Runner** has [the runner's settings](#runner-settings) and a card for |
| 178 | each kind of job. |
| 179 | |
| 180 | A button that asks the app to do something, such as **Check for updates**, |
| 181 | **Restart now**, **Retry**, **Start** or **Stop**, shows a spinner and |
| 182 | can't be pressed again until what it asked for shows: the runner's state |
| 183 | changes, the answer comes, or, after 20 seconds with no change, it is |
| 184 | yours to press again. If the app couldn't do it, the settings say why. |
| 185 | |
| 186 | ### Developer tools |
| 187 | |
| 188 | When a page goes wrong, such as one that says *Something went wrong*, the |
| 189 | web inspector shows why: the page's console, its network requests and its |
| 190 | code. It is off unless you turn on **Developer tools** in the settings' |
| 191 | **Window** section. Then any of these opens it for the page in the window: |
| 192 | |
| 193 | - **F12**, on the page. |
| 194 | - **Ctrl+Shift+I** on Windows and Linux, **⌥⌘I** (Cmd+Option+I) on macOS. |
| 195 | - **Developer tools** in the View menu. |
| 196 | |
| 197 | On macOS and Linux the same keys, or the menu row, close it again; on |
| 198 | Windows, close the inspector's own window. With the setting off, none of |
| 199 | them open it, and the View menu's row is greyed out. On Windows the change |
| 200 | takes effect at once; on macOS and Linux it takes effect when g1t |
| 201 | restarts, and the settings offer **Restart now**. |
| 202 | |
| 203 | g1t's pages can open it too, from `window.g1tDesktop.devtools.open()`, |
| 204 | which works only while the setting is on and only for g1t's own pages. |
| 205 | |
| 206 | ## The runner |
| 207 | |
| 208 | The app runs a [self-hosted runner](/guides/self-hosted-runners/) for |
| 209 | you while it is open: your workspace's jobs that ask for `self-hosted` |
| 210 | run on your computer, at no cost, and nothing has to be downloaded, |
| 211 | registered or started by hand. It starts a few seconds after g1t's page has loaded |
| 212 | (or after 20 seconds without it), and stops when g1t quits. It runs apart |
| 213 | from the window: a runner that fails starts again on its own, and never takes |
| 214 | the app down with it. Time on it is free, as on any of your |
| 215 | runners. |
| 216 | |
| 217 | To stop it, press **Stop** in [the runner menu](#the-runner-menu), or |
| 218 | **Stop running jobs** in the tray; it starts again with **Start**, or the |
| 219 | next time g1t opens. To keep it off, turn off **Run jobs on this computer |
| 220 | while g1t is open** in [the runner's settings](#runner-settings). |
| 221 | |
| 222 | Sandboxed, each kind of job has its own line in the runner menu and card |
| 223 | in the settings, **Linux jobs** and **Windows jobs**, each with its own **Stop** |
| 224 | and **Start**. Stopping Windows jobs leaves Linux jobs running, and the |
| 225 | other way round; a kind you stop stays stopped, across restarts, until you |
| 226 | start it again. Both are on until you stop one. |
| 227 | |
| 228 | A job still runs only on a runner with every label it names. The app's |
| 229 | runner has `self-hosted`, its OS and architecture (`linux` for a runner |
| 230 | whose jobs run in containers, whatever the computer is), and `desktop`. |
| 231 | It is named after your computer, and a new registration from the same |
| 232 | computer takes the place of the old one. Sandboxed, the computer has a |
| 233 | runner for each kind of job it can run, named after it with `-linux` or |
| 234 | `-windows`: `build-box-linux` has `linux`, and `build-box-windows` has |
| 235 | `windows`, on a Windows computer with Windows Sandbox. |
| 236 | |
| 237 | ### The runner menu |
| 238 | |
| 239 | The runner's dot, right beside **Settings** in the title bar, opens its |
| 240 | menu, under the dot. The runner's row in the tray opens it too. It shows, |
| 241 | live: |
| 242 | |
| 243 | - What the runner is doing, how jobs run, the workspace and the runner's |
| 244 | version, with **Stop** or **Start** for the whole runner. |
| 245 | - When the runner needs you, why, and the fix with its buttons. |
| 246 | - Each kind of job, sandboxed: its state, the job it is running with a link |
| 247 | to its run, a newer runner waiting for it, why it isn't running and the |
| 248 | fix, and its own **Stop** or **Start**. |
| 249 | - When the app last looked for a newer runner, with **Check for runner |
| 250 | updates**. |
| 251 | - The last lines of the runner's log, with **Open the whole log**. |
| 252 | - **Runner settings…**, which opens [the settings](#settings) at Runner. |
| 253 | |
| 254 | Escape, a click outside it, or the dot again closes it. While the window |
| 255 | shows no page of g1t's, the dot and the tray open the Runner window |
| 256 | instead: the same, in a window of its own. |
| 257 | |
| 258 | ### Runner settings |
| 259 | |
| 260 | The settings' **Runner** section has a card for each kind of job, as the |
| 261 | menu has them with more detail (its runner's name on g1t, its version and |
| 262 | isolation), and these: |
| 263 | |
| 264 | | Setting | Default | What it does | |
| 265 | | --- | --- | --- | |
| 266 | | **Run jobs on this computer while g1t is open** | On | Starts the runner a few seconds after g1t's page loads. Off, nothing runs. | |
| 267 | | **How jobs run** | Sandboxed | Sandboxed, in Docker, or directly on this computer. See [how jobs run](#how-jobs-run). | |
| 268 | | **Linux jobs**, **Windows jobs** (sandboxed) | Both on | Each kind of job's card has its own **Stop** and **Start**, which leave the other kind as it is. | |
| 269 | | **Workspace** | The one you were in when it first registered | The workspace whose jobs the runner runs. Lists the workspaces you own. | |
| 270 | |
| 271 | Choosing **In Docker** or **Directly on this computer** opens the Runner |
| 272 | window, a page that comes with the app, and you choose it there. Jobs |
| 273 | outside the sandbox can reach your files, so the app takes that choice |
| 274 | only from its own pages, never from a page g1t's server sends; going back |
| 275 | to **Sandboxed** works from either. |
| 276 | |
| 277 | [Seeing it](#seeing-it) says what else it shows. |
| 278 | |
| 279 | ### How jobs run |
| 280 | |
| 281 | **How jobs run**, in [the runner's settings](#runner-settings), decides what a job on your computer can |
| 282 | reach. The app never changes it by itself: when the one you chose cannot |
| 283 | start, it says why and runs nothing. |
| 284 | |
| 285 | | Choice | How | [Isolation](/guides/self-hosted-runners/#isolation) | What a job can reach | |
| 286 | | --- | --- | --- | --- | |
| 287 | | **Sandboxed** (the default) | [The sandbox](/guides/self-hosted-runners/#sandbox-on-your-computer), which the app sets up and starts itself. Linux jobs run in a small Linux VM of the runner's own, each in a container inside it: a WSL 2 distribution on Windows, a VM under Apple's Virtualization framework on macOS, and on Linux the runner's image under [Sysbox](https://github.com/nestybox/sysbox), or a VM under QEMU with KVM. On Windows 11 Pro, Enterprise and Education, Windows jobs run too, each in a Windows Sandbox of its own. | `nested-container`; `vm` for Windows jobs | Its own container, or its own Windows Sandbox. Not your computer. | |
| 288 | | **In Docker** | `g1t-runner` on your computer, driving your Docker. Each job is a container of its own. | `container` | Its own container; but the runner controls your Docker, which can reach your files (Docker Desktop shares your home folder with its VM), so this is not a sandbox. | |
| 289 | | **Directly on this computer** | `g1t-runner` on your computer, each job a process in a folder of its own. For jobs that need the system itself, such as building a Windows installer. | `host` | Everything your account can: your files, your keys, what an earlier job left. Not a sandbox. Never given a public repository's work. | |
| 290 | |
| 291 | What the sandbox needs on each computer, and how the app gets it there, |
| 292 | is in [getting the runner running](#getting-the-runner-running). |
| 293 | |
| 294 | The sandbox keeps jobs from your computer, not your computer from the |
| 295 | sandbox: anything running as your account can look inside it while a job |
| 296 | runs. So don't choose **Directly on this computer** under the same |
| 297 | account you use for the sandbox, and don't run software you don't trust |
| 298 | there. A runner registered for running jobs directly stays registered when |
| 299 | you choose another way, so remove it once you no longer use it: |
| 300 | `g1t-runner remove --dir <data folder>/host`, with the data folder below. |
| 301 | `g1t-runner sandbox status` warns while one is there. A job's secrets go from inside the sandbox |
| 302 | straight to g1t, the job's token left on your computer is spent once the |
| 303 | job has started, and the runner's folders are yours alone. [What your |
| 304 | computer can see](/guides/self-hosted-runners/#what-your-computer-can-see) |
| 305 | has the details. |
| 306 | |
| 307 | For the sandbox, the app runs the same commands you would, with its own |
| 308 | copy of `g1t-runner` and its state in the app's local data folder, which |
| 309 | never roams to other computers with your profile |
| 310 | (`%LOCALAPPDATA%\sh.g1t.desktop\runner` on Windows, or |
| 311 | `%APPDATA%\sh.g1t.desktop\runner` where an earlier version set it up; |
| 312 | `~/Library/Application Support/sh.g1t.desktop/runner` on macOS; |
| 313 | `~/.local/share/sh.g1t.desktop/runner` on Linux): |
| 314 | |
| 315 | | When | The app runs | |
| 316 | | --- | --- | |
| 317 | | A few seconds after g1t's page loads | `g1t-runner sandbox up --json --state-dir <data folder>/sandbox --url <server> --name <computer> --labels desktop`, with the registration token the first time only, in its environment as `G1T_RUNNER_TOKEN`, never on its command line, where anyone on the computer could read it. The first `up` downloads and checks the sandbox's image and makes the VM, which takes a few minutes. | |
| 318 | | Every few seconds while it runs | `g1t-runner sandbox status --json`, for the tray, the settings and the Runners page. | |
| 319 | | When g1t quits, or you press **Stop running jobs** | `g1t-runner sandbox down`: a job that is running is cut short. | |
| 320 | | When you press **Stop** on one kind of job's card | `g1t-runner sandbox down --only windows` (or `linux`): that kind stops, a job of its own cut short, and stays off; the other runs on. Every `up` names the kinds that are on, `--only linux,windows`, so one you stopped never starts by itself. | |
| 321 | | When you press **Start** on one kind of job's card | `g1t-runner sandbox up --only windows` (or `linux`), leaving the other as it is. A kind never registered is registered first, with a token as above. | |
| 322 | | While one kind of job runs and the other should and doesn't | `g1t-runner sandbox up --only` it again, by itself: every five minutes while the newest release has no sandbox images, else after a wait that grows each time, up to ten minutes. **Retry** or **Check now** tries at once. | |
| 323 | | When you choose another way of running jobs | `g1t-runner sandbox down --drain`, once the job that is running ends. The sandbox keeps its registration, so choosing Sandboxed again needs no new one. | |
| 324 | | With a new release, once Linux jobs have no job | `g1t-runner sandbox update`: the newest signed image, the same registration. Windows jobs run on meanwhile. | |
| 325 | | With a new release, once Windows jobs have no job | `g1t-runner sandbox down --only windows --drain`, the new `g1t-runner` put in place, then `g1t-runner sandbox up --only windows`. Their runner is `g1t-runner` itself, so they stop while it is replaced, a few seconds; Linux jobs run on meanwhile. | |
| 326 | |
| 327 | The other two choices run `g1t-runner` from the same data folder, with |
| 328 | each one's registration beside it. |
| 329 | |
| 330 | On Windows the sandbox is the WSL distribution `g1t-sandbox`, of which a |
| 331 | computer has one. If this copy of g1t has no record of making the one |
| 332 | there (you made it with `g1t-runner sandbox up`, or g1t was uninstalled |
| 333 | with its data deleted and installed again), the app leaves it alone and |
| 334 | says *this computer has another sandbox*: **Remove it and start again** |
| 335 | removes it, with its VM and registration, and makes the app's own; or keep |
| 336 | it and turn the app's runner off. Uninstalling g1t with **Delete the |
| 337 | application data** ticked removes the sandbox too. |
| 338 | |
| 339 | ### Getting the runner running |
| 340 | |
| 341 | The sandbox is a small virtual machine, so it needs what any VM needs: |
| 342 | virtualization on in your computer, and on Windows the parts of Windows |
| 343 | that run Linux VMs. You don't need to know what those are. Before it |
| 344 | downloads anything, the app asks `g1t-runner sandbox status` what your |
| 345 | computer still lacks for each kind of job, and each kind's card says it in |
| 346 | plain words: what is missing, why, and one button that fixes it, or the |
| 347 | exact steps when only you can. |
| 348 | |
| 349 | | Computer | Linux jobs need | Windows jobs need | |
| 350 | | --- | --- | --- | |
| 351 | | Windows 11 (any edition), Windows 10 2004 or later | Virtualization on, the Virtual Machine Platform feature, and WSL 2.0 or later. **Set up** does the last two. | Windows 11 Pro, Enterprise or Education, 24H2 or later; virtualization on; the Windows Sandbox feature. **Set up** turns it on. | |
| 352 | | macOS 13 or later, Apple silicon or Intel | [vfkit](https://github.com/crc-org/vfkit), from [Homebrew](https://brew.sh): `brew install vfkit`. | Not released yet. | |
| 353 | | Linux | Sysbox 0.7 or later in Docker; or virtualization on, KVM, and QEMU. | None: Linux jobs are this computer's own. | |
| 354 | |
| 355 | Each kind of job is set up on its own: Windows jobs that can't run on |
| 356 | Windows Home never stop Linux jobs, and Linux jobs waiting on WSL never |
| 357 | stop Windows jobs. What is missing is looked at again within half a minute, so |
| 358 | a card changes by itself once you have fixed it; **Check now** looks at |
| 359 | once. |
| 360 | |
| 361 | **On Windows, Set up does what Windows can do itself, in one go.** It turns |
| 362 | on Virtual Machine Platform and Windows Sandbox, for the kinds of job you |
| 363 | have on, and installs or updates WSL. Windows asks you to allow it, once |
| 364 | (on a standard account, an administrator types their password). The cards |
| 365 | say *Setting up* meanwhile, a few minutes. When what it turned on takes a |
| 366 | restart, they say *Restart needed*, with **Restart now** and **Later**. |
| 367 | **Restart now** asks first, in a Windows dialog of its own (*Restart |
| 368 | Windows now to finish setting up the runner?*, with No chosen until you |
| 369 | choose Yes), so save your work before you answer; a page can't restart |
| 370 | your computer without you. Either way, g1t opens once by itself the next |
| 371 | time you sign in to Windows, whether or not it opens at sign-in anyway, |
| 372 | and carries on: Linux jobs download their image and start. Until Windows |
| 373 | has restarted, the cards keep saying *Restart needed*. |
| 374 | |
| 375 | If a step fails after a feature was turned on, the cards still ask for the |
| 376 | restart, and offer **Set up** again after it for what is left. Set up is |
| 377 | the same as running these in an admin terminal, and its log goes into the |
| 378 | runner's (**View log**): |
| 379 | |
| 380 | ```powershell |
| 381 | Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart |
| 382 | Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All -NoRestart |
| 383 | wsl --install --no-distribution --web-download # or wsl --update --web-download, for an older WSL |
| 384 | ``` |
| 385 | |
| 386 | It turns on only the features that are off, for the kinds of job that are |
| 387 | on. WSL is downloaded directly first (`--web-download`), which needs no |
| 388 | Microsoft Store; if that fails, the same command runs again without it, |
| 389 | through the Store. |
| 390 | |
| 391 | Set up is for Windows alone. On Linux and macOS nothing the sandbox needs |
| 392 | can be installed without your password in a terminal, so the card gives |
| 393 | the command, with **Copy command**, and changes by itself once it has |
| 394 | run. The sandbox has been checked end to end on Windows; on macOS and on |
| 395 | Linux without Sysbox, the checks and commands below are what the app does, |
| 396 | but the VMs themselves [have not yet been run there](/guides/self-hosted-runners/#what-it-cannot-stop). |
| 397 | |
| 398 | Whatever is missing, nothing falls back to running jobs in Docker or |
| 399 | directly on your computer: those are only ever [your choice](#how-jobs-run). |
| 400 | |
| 401 | #### On Windows |
| 402 | |
| 403 | | The card says | What is missing | What to do | |
| 404 | | --- | --- | --- | |
| 405 | | *Needs setting up*: *WSL isn't installed*, *Virtual Machine Platform is off*, *WSL needs an update* | WSL 2, which the Linux VM runs on: the Virtual Machine Platform feature, and WSL 2.0 or later from the Microsoft Store (not the one built into older Windows). | **Set up**, and restart if it asks. | |
| 406 | | *Needs setting up*: *Windows Sandbox is off* | The Windows Sandbox feature, which each Windows job runs in. | **Set up**, then restart. | |
| 407 | | *Not available*: *Not in Windows Home* | Windows Sandbox, which Windows Home doesn't have. Linux jobs run all the same. | Nothing, for Linux jobs. For Windows jobs, Windows 11 Pro, Enterprise or Education: **Open Activation** is where Windows upgrades. | |
| 408 | | *Restart needed*: *Restart to finish setting up* | Set up turned on a Windows feature, which takes effect after a restart. | **Restart now**, or **Later** and restart when it suits you. g1t opens again after and carries on. | |
| 409 | | *Virtualization is off* | Intel VT-x or AMD-V, turned off in your computer's firmware, where Windows can't turn it on. Said on Windows jobs too, when Windows Sandbox is on but could not start. | [Turn on virtualization](#turning-on-virtualization) (**How to turn it on** opens these steps), then **Check now**. | |
| 410 | | *This VM can't run the sandbox* | g1t is in a virtual machine whose host doesn't pass virtualization through to it. Said once the sandbox's VM has failed to start for that reason, since it can't be known before. | [Turn on nested virtualization](#in-a-virtual-machine) on the host (**How to turn it on**). | |
| 411 | | *Windows needs an update*, on Linux jobs | Windows older than Windows 10 version 2004, the first with WSL 2. | **Open Windows Update**, update, and restart. | |
| 412 | | *Windows needs an update*, on Windows jobs | Windows Sandbox's command line, `wsb`, which came with Windows 11 24H2. | **Open Windows Update**, update to 24H2 or later, and restart. | |
| 413 | | *Set up didn't finish* | You said No to Windows' prompt, or a step failed, with its reason. | **Set up** again; **View log** says what happened. | |
| 414 | | *WSL uses mirrored networking* | A setting, not a part: `networkingMode=mirrored` in `%USERPROFILE%\.wslconfig` lets Linux reach your computer's own `localhost`, so the sandbox won't start with it. | Remove it, run `wsl --shutdown`, then **Retry**. | |
| 415 | |
| 416 | #### On Linux |
| 417 | |
| 418 | With Sysbox 0.7 or later in Docker, none of these is needed: the runner's |
| 419 | image runs under Sysbox, without a VM. Without it, Linux jobs run in a VM |
| 420 | under QEMU with KVM, and the card says what is missing for that, with the |
| 421 | command that fixes it on **Copy command**. |
| 422 | |
| 423 | | The card says | What is missing | What to do | |
| 424 | | --- | --- | --- | |
| 425 | | *No access to KVM* | `/dev/kvm` is there, and your account may not use it. | `sudo usermod -aG kvm $USER`, then log out and back in. | |
| 426 | | *KVM isn't loaded* | `/dev/kvm`, though your processor can run VMs. | `sudo modprobe kvm_intel` (Intel) or `sudo modprobe kvm_amd` (AMD). If it says the firmware disabled it, [turn on virtualization](#turning-on-virtualization). | |
| 427 | | *QEMU isn't installed* | QEMU, which runs the VM. | `sudo apt install qemu-system-x86` (`qemu-system-arm` on Arm) on Debian and Ubuntu, `sudo dnf install qemu-kvm` on Fedora, `sudo pacman -S qemu-base` on Arch, `sudo zypper install qemu-kvm` on openSUSE. | |
| 428 | | *Virtualization is off* | Your processor says it can't run VMs: virtualization is off in the firmware, or it has none. | [Turn on virtualization](#turning-on-virtualization), or install Sysbox. | |
| 429 | | *This VM can't run the sandbox* | Linux in a VM whose host doesn't pass virtualization through. | [Turn on nested virtualization](#in-a-virtual-machine), or install Sysbox. | |
| 430 | |
| 431 | #### On macOS |
| 432 | |
| 433 | | The card says | What is missing | What to do | |
| 434 | | --- | --- | --- | |
| 435 | | *vfkit isn't installed*, with **Get Homebrew** | vfkit, and Homebrew, which installs it. | **Get Homebrew** and install it, then `brew install vfkit` in Terminal (**Copy command**). | |
| 436 | | *vfkit isn't installed* | vfkit, which runs the VM with Apple's Virtualization framework. | `brew install vfkit` in Terminal (**Copy command**). | |
| 437 | | *macOS needs an update* | macOS 13 or later. | **Open Software Update**, update, and open g1t again. | |
| 438 | |
| 439 | The VM's image is the one for your Mac's processor, Apple silicon or Intel; |
| 440 | while a release has none for it yet, the card says *Waiting for image*. |
| 441 | Every Mac g1t runs on has virtualization on. |
| 442 | |
| 443 | #### Turning on virtualization |
| 444 | |
| 445 | Virtualization (Intel VT-x, *Intel Virtualization Technology*; AMD-V, |
| 446 | *SVM Mode*) is a setting in your computer's firmware, the BIOS or UEFI |
| 447 | settings, which only you can change. Most computers have it on; some |
| 448 | come with it off. |
| 449 | |
| 450 | 1. Open the firmware settings. On Windows: **Settings**, **System**, |
| 451 | **Recovery**, **Advanced startup**, **Restart now**, then |
| 452 | **Troubleshoot**, **Advanced options**, **UEFI Firmware Settings**, |
| 453 | **Restart**. Or press its key as the computer starts: usually F2 (Dell, |
| 454 | Acer, ASUS, Lenovo IdeaPad), F10 (HP), F1 (Lenovo ThinkPad), or Del |
| 455 | (desktops: MSI, Gigabyte, ASRock). |
| 456 | 2. Find **Intel Virtualization Technology** (sometimes **VT-x** or **Intel |
| 457 | VT**) or **SVM Mode** (AMD), usually under **Advanced**, **CPU |
| 458 | Configuration** or **Security**, and turn it on. |
| 459 | 3. Save and exit, usually F10. Windows starts again, and the card changes |
| 460 | by itself. |
| 461 | |
| 462 | #### In a virtual machine |
| 463 | |
| 464 | g1t inside a VM runs the sandbox as a VM inside that VM, which works only |
| 465 | when the host passes virtualization through: *nested virtualization*. Turn |
| 466 | it on for the VM on its host, with the VM off, then start it again: |
| 467 | |
| 468 | | Host | How | |
| 469 | | --- | --- | |
| 470 | | Hyper-V | `Set-VMProcessor -VMName <name> -ExposeVirtualizationExtensions $true`, in an admin PowerShell on the host. | |
| 471 | | VMware Workstation, Fusion | The VM's settings, **Processors**, **Virtualize Intel VT-x/EPT or AMD-V/RVI**. | |
| 472 | | VirtualBox | The VM's settings, **System**, **Processor**, **Enable Nested VT-x/AMD-V**, or `VBoxManage modifyvm <name> --nested-hw-virt on`. | |
| 473 | | Proxmox, KVM | The VM's processor type `host`. | |
| 474 | | A cloud VM | A machine type with nested virtualization: on Azure, Dv3 and Ev3 or later; on Google Cloud, nested virtualization turned on for the instance. Elsewhere, ask your provider: some offer it only on bare-metal machines. | |
| 475 | |
| 476 | ### Registering |
| 477 | |
| 478 | The first time, and whenever you change the workspace or how jobs run, |
| 479 | the app registers your computer with the workspace. It needs you signed |
| 480 | in to g1t in the app as an owner of the workspace, since only owners add |
| 481 | runners: the page you are on makes a registration token, which lasts an |
| 482 | hour, and hands it to the app, which gives it to the runner once. The |
| 483 | token is never shown, and is not kept. From then on the runner starts |
| 484 | from its registration, signed in or not. |
| 485 | |
| 486 | The workspace is the one you were in when it first registered; choose |
| 487 | another under **Workspace** in [the runner's settings](#runner-settings). Changing it, or how jobs |
| 488 | run, waits for a job that is running to end, then removes the old |
| 489 | registration and makes a new one. The sandbox is registered with one |
| 490 | workspace, so moving it to another removes it and makes it again, image |
| 491 | and all; its old runners stay listed on g1t, offline, until you remove |
| 492 | them there. |
| 493 | |
| 494 | ### Keeping it up to date |
| 495 | |
| 496 | The app keeps the runner up to date. Soon after it starts, then every |
| 497 | hour, it looks for a newer `g1t-runner` in |
| 498 | `g1t.sh/downloads/runner/latest.json`, while the runner carries on: |
| 499 | |
| 500 | 1. **It checks the release is g1t's.** The manifest's Ed25519 signature, |
| 501 | `latest.json.sig`, must check out against g1t's release key, which is |
| 502 | built into the app. A manifest without one, or whose signature |
| 503 | doesn't check out, is refused, and nothing in it is used: the app says |
| 504 | *Update refused: not signed by g1t* and keeps the runner it has. |
| 505 | 2. **It downloads the new `g1t-runner`** and checks it against the |
| 506 | SHA-256 the signed manifest names, throwing away one that differs. |
| 507 | 3. **It puts it in, one kind of job at a time, as each is idle.** A job |
| 508 | is never cut short for an update. Sandboxed, Linux jobs take the |
| 509 | release's image (`g1t-runner sandbox update`, which checks its |
| 510 | signature and SHA-256 itself) as soon as they have no job, and |
| 511 | Windows jobs, whose runner is `g1t-runner` itself, stop after their |
| 512 | job, take the new program and start again, while the other kind runs |
| 513 | on. In Docker or directly on this computer, the runner stops between |
| 514 | jobs and starts on the new one. |
| 515 | |
| 516 | Meanwhile each card says what is waiting: *0.3.2 ready, installs after |
| 517 | this job*. **Check for runner updates**, in [the runner menu](#the-runner-menu), |
| 518 | looks at once, and installs what it finds the same way. An |
| 519 | update that fails leaves the runner as it was, and the next hour's look |
| 520 | tries again. Turning off **Download updates by themselves** stops the |
| 521 | hourly look; **Check for runner updates** still looks, and installs. |
| 522 | |
| 523 | ### Seeing it |
| 524 | |
| 525 | | Where | What it shows | |
| 526 | | --- | --- | |
| 527 | | The title bar | Its dot, right beside **Settings**, in the colour of what it is doing; hover it for the words (*Runner running*, *Running a job*, *Running 2 jobs*, *Runner starting*, *Runner setting up*, *Runner stopped*, *Runner needs you*), which a wide window shows beside it. It opens the runner menu. | |
| 528 | | The tray | A row with what the runner is doing, *Runner: Waiting for jobs*, which opens the runner menu; **Stop running jobs** or **Start running jobs** under it. The icon's hover text says it too. | |
| 529 | | [The runner menu](#the-runner-menu) | At the top, what the whole runner is doing, as the dot says it, with how jobs run, its workspace and version, and its own **Stop** or **Start**. When it needs you, only what is about the whole runner: signed out, no workspace, turned off, stopped, the sandbox down, with the fix's buttons. Sandboxed, a line for each kind of job: its state (*Running a job*, *Waiting for jobs*, *Starting*, *Downloading image* with how far, *Updating*, *Waiting for image*, *Needs setting up*, *Setting up*, *Restart needed*, *Stopped*, *Not available*, *Problem*), the job it is running with a link to it, a newer runner waiting for it (*0.3.2 ready, installs after this job*), and when it isn't running why and the fix, with the fix's buttons and its own **Stop** or **Start**. Then when the app last looked for a newer runner, with **Check for runner updates**; the last lines of its log, following along, with **Open the whole log**; and **Runner settings…**. | |
| 530 | | [The runner's settings](#runner-settings) | The same, with a card for each kind of job side by side, which adds its runner's name on g1t, version, updates and isolation; then **Run jobs on this computer while g1t is open**, how jobs run, the workspace, and your computer's name, the runner's version and when the app last looked for a newer one, with **View on g1t**. In Docker or directly on this computer, one line says what it is doing, or why it isn't running and the fix. | |
| 531 | | The workspace's [Runners page](/guides/self-hosted-runners/#the-runners-page) | **Desktops**: every computer with the app in the workspace, with what each is doing, or why it isn't running and the fix, in the same words; a sandboxed one's kinds of job as cards of their own, as in the settings, with a link to the run each is running, its version, when the app last looked for updates and a newer one waiting. Inside the app, this computer comes first, live, with its buttons, each kind's **Stop** or **Start** and **Check for runner updates** among them. A computer whose g1t is closed says *g1t is closed on* its name. | |
| 532 | |
| 533 | ### When it isn't running |
| 534 | |
| 535 | Each state says why, and how to fix it, in the same words in the tray, |
| 536 | the settings and the Runners page. |
| 537 | |
| 538 | | It says | Why | What to do | |
| 539 | | --- | --- | --- | |
| 540 | | *Waiting for jobs* | It is registered and listening. | Nothing. | |
| 541 | | *Running* a job | It is running that job. | Nothing; the Runners page links to its run. | |
| 542 | | *Starting*, *Registering with* a workspace, *Updating* | It is on its way. | Wait a few seconds. | |
| 543 | | *Not running: turned off* | **Run jobs on this computer while g1t is open** is off. | **Turn on**. | |
| 544 | | *Not running: stopped* | You pressed **Stop running jobs** in the tray. | **Start**, or open g1t again. | |
| 545 | | *Not running: every kind of job is stopped* | You stopped Linux jobs and Windows jobs, each on its card. | **Start** on one. | |
| 546 | | *Linux jobs: Stopped*, *Windows jobs: Stopped*, *You stopped* them | You pressed **Stop** on that card. The other kind runs on. | **Start** on the card. | |
| 547 | | *Linux jobs: Waiting for image*: *Waiting for the sandbox's image* | The newest `g1t-runner` is published without the sandbox's images yet (or without this kind of computer's), so there is nothing to download. | Nothing: g1t looks again every five minutes and starts Linux jobs once they're out. **Check now** looks at once. | |
| 548 | | *Not running: signed out* | It isn't registered yet, and registering needs you signed in. | **Sign in**, as an owner of the workspace. | |
| 549 | | *Not running: no workspace to run jobs for* | You don't own a workspace, and only owners add runners. | Ask an owner, or **Create a workspace**. | |
| 550 | | *Couldn't register with* a workspace: *only its owners can* | You aren't an owner of it. | Ask an owner to make you one, or **Choose workspace**. | |
| 551 | | *Couldn't register with* a workspace, with g1t's reason | g1t refused the registration, such as for too many tokens in an hour. | **Retry**; it also tries again by itself. | |
| 552 | | *Not running: Docker isn't running* | Running jobs in Docker needs Docker, and it isn't running or isn't installed. | **Open Docker** (Docker Desktop), or **Get Docker**. It starts by itself once Docker answers. | |
| 553 | | *Needs setting up*, *Setting up*, *Restart needed* on a card, and *Not running:* what it needs (*WSL isn't installed*, *virtualization is off*, …) | Your computer lacks something the sandbox needs: WSL, a Windows feature, virtualization, KVM, QEMU, vfkit. | **Set up** on Windows, or the card's steps. [Getting the runner running](#getting-the-runner-running) has a row for each, on each system. | |
| 554 | | *Not running: WSL uses mirrored networking* | `networkingMode=mirrored` in `%USERPROFILE%\.wslconfig` lets Linux reach your computer's own `localhost`. | Remove it, run `wsl --shutdown`, then **Retry**. | |
| 555 | | *Not running: WSL isn't installed*, *virtualization is off*, *vfkit isn't installed*, *no Sysbox or KVM*, with **Copy command** or **Open Windows features** | The same, said by an older `g1t-runner`, from before it named what a computer lacks. | Its fix; the app downloads a newer `g1t-runner` by itself, which brings **Set up**. | |
| 556 | | *Not running: the sandbox's image didn't download* | The image couldn't be fetched from g1t, with the reason. | It tries again by itself, waiting longer each time; check that your computer can reach g1t. **Retry** tries now. | |
| 557 | | *Not running: the sandbox's image didn't check out* | The image that downloaded isn't the one the release signed (its signature or SHA-256), so it wasn't used. | It downloads it again by itself. If it keeps happening, something between your computer and g1t, such as a proxy or antivirus, is changing downloads: **Report** it. | |
| 558 | | *Not running: the sandbox can't run here* | Something else the sandbox needs, in its own words. | What it says. | |
| 559 | | *Not running: the sandbox failed* | The sandbox stopped, or didn't start, with its reason. | It starts again by itself, waiting longer each time. **Retry**, or **View log**. | |
| 560 | | *Not running: this computer has another sandbox* | A sandbox this copy of g1t has no record of making: one you made with `g1t-runner sandbox up`, or one left from before g1t was installed again. A computer has one. | **Remove it and start again**, which asks first; its old runners stay listed on g1t, offline, until you remove them there. Or keep it, and turn the app's runner off. | |
| 561 | | *Not running: this g1t-runner has no sandbox* | The app's `g1t-runner` is from before the sandbox. | It downloads a newer one by itself; **Retry** looks now. | |
| 562 | | *Windows jobs: Not available*: *Not in Windows Home* | Windows Home has no Windows Sandbox. Linux jobs still run. | Nothing, for Linux jobs; Windows jobs need Pro, Enterprise or Education. | |
| 563 | | *Windows jobs: Problem*: *Its runner didn't start* or *Its runner stopped* | The runner for Windows jobs didn't start, with why, or stopped by itself, while Linux jobs run. | It is started again by itself in a few minutes; **Retry** now, or **View log**. | |
| 564 | | *macOS jobs: Not available*: *Not released yet* | Sandboxed macOS jobs aren't released. | Nothing: they come with a `g1t-runner` update, which the app downloads by itself. | |
| 565 | | *Offline:* the server *unreachable* | Your computer can't reach g1t. | Check the connection; it carries on by itself. **Retry** tries now. | |
| 566 | | *0.3.2 ready, installs after this job*, on a card | A newer `g1t-runner` is downloaded and checked, and that kind of job is running a job. | Nothing: it goes in as soon as the job ends, and the other kind runs on meanwhile. | |
| 567 | | *Update failed* | A new version couldn't be downloaded, its SHA-256 wasn't the release's, or the sandbox's image couldn't be updated. | It keeps running the version it has, and tries again within the hour. **Check again** now; **Report** it if it keeps failing. | |
| 568 | | *Update refused: not signed by g1t* | The newest release's manifest has no signature, or one that isn't g1t's release key's, so nothing in it was used. | Nothing to fix on your side: it keeps running the version it has, and looks again within the hour (**Check again** looks now). If it keeps happening, something between your computer and g1t, such as a proxy or antivirus, is changing downloads: **Report** it. | |
| 569 | | *Not running: the runner's release isn't signed by g1t* | As above, before any `g1t-runner` was installed, so there is none to run. | It tries again by itself in a few minutes; **Retry** now, or **Report** it if it keeps happening. | |
| 570 | | *Runner stopped (exit code* N*)* | The runner ended by itself, with the reason from its log. | It starts again by itself, waiting longer each time. **Restart** now, or **View log**. | |
| 571 | | *g1t is closed on* a computer | Seen on the Runners page: g1t hasn't been open on that computer for ten minutes. | Open g1t there. | |
| 572 | |
| 573 | ## Links |
| 574 | |
| 575 | A **`g1t://` link** opens a page in the app: `g1t://acme/-/chat/dm/chn_1` |
| 576 | is `g1t.sh/acme/-/chat/dm/chn_1`. The installer registers the scheme; a |
| 577 | link opened while the app is running moves it to the page without a |
| 578 | reload, and one opened while it is not starts it there. Scripts, launchers |
| 579 | and other apps on your computer can use it. |
| 580 | |
| 581 | A link to another site opens in the browser your system uses; the window |
| 582 | stays on g1t. That includes this documentation and the status page. So do |
| 583 | g1t's own pages for reading about g1t rather than using it: pricing, the |
| 584 | policies, security, support and the downloads. Links on g1t that would |
| 585 | open a new tab open in the window instead, as it has no tabs. Signing in |
| 586 | with GitHub is the one trip outside g1t that stays in the window. |
| 587 | |
| 588 | ## Updates |
| 589 | |
| 590 | The app asks `g1t.sh/downloads/desktop/latest.json` for a newer version |
| 591 | as it starts and every hour, and downloads one in the background. |
| 592 | |
| 593 | - **As it starts**, a newer version is installed straight away, and g1t |
| 594 | opens again on it a moment later, before you have begun working in it. |
| 595 | If something in the app misbehaves, quitting and opening g1t again is |
| 596 | enough to be on the newest version. The one exception is your runner |
| 597 | in the middle of a job, which is never cut short: then the update waits |
| 598 | like any other. |
| 599 | - **Later on**, it never installs under you: a notification and the |
| 600 | tray's **Restart to update** say it is ready, and the restart, or |
| 601 | quitting, installs it. |
| 602 | |
| 603 | To see where your copy stands, choose **Check for updates…** in the Help |
| 604 | menu or the tray, or **Check for updates** in [the settings](#settings). |
| 605 | The menu and the tray open the settings at their Updates section, |
| 606 | which checks and says the answer there: |
| 607 | |
| 608 | - **Up to date. Last checked today at 10:42.** You have the newest version. |
| 609 | - **Version 0.2.0 is downloaded and installs when g1t restarts.** A |
| 610 | **Restart now** button beside it installs it and opens the new version, |
| 611 | as **Restart to update** in the Help menu and the tray do. |
| 612 | - **Could not reach g1t.sh to check.** Try again once you are online. |
| 613 | |
| 614 | A check finds and downloads a new version in one go, so the answer can |
| 615 | take a moment on a slow connection. The automatic checks and yours are the |
| 616 | same check: a version the background found is shown as downloaded when |
| 617 | you look. To stop the app checking on its own, turn off |
| 618 | **Download updates by themselves** in [the settings](#settings). |
| 619 | |
| 620 | Every release is signed with g1t's key, whose public half is built into |
| 621 | the app; a download whose signature does not check out is thrown away. |
| 622 | Because the window shows the site itself, most changes to g1t need no |
| 623 | update at all: the app updates when something native changes. |
| 624 | |
| 625 | ## Your own g1t |
| 626 | |
| 627 | If you [run g1t yourself](/guides/self-hosting/), point the app at it: |
| 628 | **Use another g1t…** in the tray or the File menu, or **Change…** in [the |
| 629 | settings](#settings), then your server's address, such as |
| 630 | `https://g1t.example.com`. The app keeps it and opens there from then on; |
| 631 | **Use g1t.sh** on the same page goes back. Only that server's pages can |
| 632 | talk to the app, whichever it is, and updates still come from g1t.sh. |
| 633 | |
| 634 | ## What's not there yet |
| 635 | |
| 636 | - **Windows jobs on a Mac.** Sandboxed macOS jobs are designed, not |
| 637 | released, so a Mac's sandbox runs Linux jobs only. |
| 638 | - **Choosing the sandbox's share of the computer.** It takes half the |
| 639 | CPUs (at most 8) and a quarter of the memory (2 to 8 GB); the app has no |
| 640 | setting for it yet. |
| 641 | - **Opening the conversation from a notification.** Clicking one brings |
| 642 | the app forward; the page it is about is coming. |
| 643 | - **A page of its own while offline.** If the network goes away while a |
| 644 | page is open, the window shows the web view's own error until it is |
| 645 | back; starting without a network shows the app's own page, with a retry. |
| 646 | - **Notarization on macOS**, so the first open needs no right-click. |
| 647 | - **A phone app.** It is being built: see [the phone app](/guides/mobile/). |
| 648 | |
| 649 | ## For operators: releasing the app |
| 650 | |
| 651 | The app lives in `apps/desktop` in [g1t's repository](https://g1t.sh/flagon-io/g1t): |
| 652 | a Tauri shell in Rust under `src-tauri`, and a launcher page it bundles. |
| 653 | A release is a tag `desktop-v<version>`, where the version is the one in |
| 654 | `apps/desktop/src-tauri/Cargo.toml`: push it, and the `Desktop release` |
| 655 | workflow builds the installers, signs the updater's files, publishes the |
| 656 | release to the `g1t-downloads` bucket and points `latest.json` at it. |
| 657 | `scripts/desktop-release.mjs` does the same by hand, and its header lists |
| 658 | the files a release holds. |
| 659 | |
| 660 | | What | Where | |
| 661 | | --- | --- | |
| 662 | | The runner's release key | The app trusts a `g1t-runner` release only when its manifest is signed with g1t's runner release key, whose public half (the repository variable `RUNNER_RELEASE_PUBLIC_KEY`) is built into the app, in `src-tauri/src/runner/native.rs`. To build the app for a g1t of your own, whose runner releases you sign with your own key, set `G1T_RUNNER_RELEASE_KEY` to its public key, base64, when you build it. | |
| 663 | | The updater's signing key | `node scripts/desktop-release.mjs keygen`, once. The private key is the repository secret `DESKTOP_SIGNING_KEY`; the public key is `plugins.updater.pubkey` in `tauri.conf.json`. Losing the private key means every installed app stops updating: keep it. | |
| 664 | | Linux builds | g1t's own Linux machines, in every release. | |
| 665 | | Windows builds | Either a Windows machine registered as a [self-hosted runner](/guides/self-hosted-runners/) with the labels `self-hosted` and `windows` (Rust, Node and the Visual Studio build tools on it) and the repository variable `DESKTOP_WINDOWS_RUNNER` set to `true`; or, with no Windows machine, `DESKTOP_WINDOWS_FROM_LINUX` set to `true`, which cross-builds on Linux with `cargo-xwin` and NSIS, fetching the MSVC runtime from `aka.ms` and `download.visualstudio.microsoft.com`. | |
| 666 | | macOS builds | A Mac, registered as a self-hosted runner with the labels `self-hosted` and `macos`, and the repository variable `DESKTOP_MACOS_RUNNER` set to `true`. | |
| 667 | | A platform with no machine | Its job is skipped and the release goes out with the rest; the download page says which platforms a release lacks, and the next release fills them in. | |
| 668 | | Where releases are served | `g1t.sh/downloads/desktop/<version>/<file>`, from the same bucket as the runner's and the CLI's releases. | |
| 669 | |
| 670 | A self-hosted g1t does not serve the app's releases: the app always |
| 671 | updates from g1t.sh, and `g1t.sh/download` is where to send people. |