| 1 | --- |
| 2 | title: Workspaces |
| 3 | description: Workspaces, their names and icons, renaming and deleting one, members, owners and the roles that add to a member, inviting people, Workspace mode's settings pages, requiring two-factor authentication, access tokens that belong to a workspace, and Getting started, the setup guide for its owners. |
| 4 | --- |
| 5 | |
| 6 | A workspace owns repositories and is the first part of their address: |
| 7 | `g1t.sh/<workspace>/<repo>`. There is one kind. A workspace for just you and |
| 8 | one for a company are the same thing with a different number of members, so |
| 9 | there is no separate notion of an organization. |
| 10 | |
| 11 | ## Create a workspace |
| 12 | |
| 13 | Your account does not own repositories itself: a workspace does, and |
| 14 | repositories go in it. Every new account gets a workspace of its own, named |
| 15 | for its username and on the free plan, unless its invite brings it into |
| 16 | someone else's workspace; see |
| 17 | [your first workspace](/guides/authentication/#your-first-workspace). |
| 18 | Signed in without a workspace, g1t shows **Create your workspace or ask to |
| 19 | join one** in place of Mission control: the invitations waiting for you, |
| 20 | and the form below. |
| 21 | |
| 22 | To create another: |
| 23 | |
| 24 | 1. Open [g1t.sh/workspaces/new](https://g1t.sh/workspaces/new). |
| 25 | 2. Choose its name in URLs: lowercase letters, digits and single hyphens. |
| 26 | An owner can [change it later](#rename-a-workspace), and old addresses |
| 27 | redirect for 90 days. |
| 28 | 3. Optionally give it a display name. |
| 29 | |
| 30 | From the API, `POST /workspaces` with `slug` and `name`, or the |
| 31 | `workspace` tool's `create` action: |
| 32 | |
| 33 | ```sh |
| 34 | curl -X POST https://api.g1t.sh/workspaces \ |
| 35 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 36 | -H "Content-Type: application/json" \ |
| 37 | -d '{"slug": "acme", "name": "Acme"}' |
| 38 | ``` |
| 39 | |
| 40 | You can belong to up to ten workspaces. `GET /user`, or the `account` tool's `whoami` action, lists the |
| 41 | ones you belong to. |
| 42 | |
| 43 | A new workspace is free, and **each person can own one free workspace**. |
| 44 | While you own a free workspace, the page shows **You already own a free |
| 45 | workspace** in place of the form, with **Start the plan** on it; the API |
| 46 | answers `402` (`payment_required`). Start the plan on it, or delete it, |
| 47 | then create the new one. Several free workspaces from before are kept, but |
| 48 | each needs the plan (or deleting) before you can create another. See |
| 49 | [one free workspace per person](/guides/usage-and-billing/#one-free-workspace-per-person). |
| 50 | |
| 51 | Usernames and workspaces share one set of names, so a name means the same |
| 52 | thing wherever it appears. Your username is reserved for you: only you can |
| 53 | create a workspace with that name, and nobody can register a username that |
| 54 | is already a workspace. The names `g1t` and `g1t-agent` belong to g1t, |
| 55 | and nobody can register them. |
| 56 | |
| 57 | ## Getting started |
| 58 | |
| 59 | **Getting started** is a setup guide for a workspace's owners. It opens |
| 60 | by itself on the workspace's [Home](/guides/home/) and on its |
| 61 | **Workspace** page, for each owner, until that owner finishes or closes |
| 62 | it. A workspace made before the guide existed opens it once for each of |
| 63 | its owners too. |
| 64 | |
| 65 | It has six steps. Each is ticked from what the workspace has, never from |
| 66 | what you clicked, so a step you did elsewhere is ticked here as well: |
| 67 | |
| 68 | | Step | Done when | |
| 69 | | --- | --- | |
| 70 | | **Add an AI provider** | The workspace has an [AI provider](/guides/ai/) whose key passed its last check. You can add one in the guide: choose a provider, paste its key, and **Add and check the key** saves it and checks it at once, as the AI page does. **Test** checks one again. | |
| 71 | | **Choose Ask's model** | [Ask g1t](/guides/ask/) answers with one of the workspace's providers, and has no problem with it. Choose the provider and a model, or Auto, and **Use for Ask**. | |
| 72 | | **Bring your code** | The workspace has a project, or [GitHub is connected](/guides/github/). **New project** starts one; **Connect GitHub** installs g1t's GitHub App in one step, then you choose the repositories to bring across. | |
| 73 | | **Connect your harness** | You signed in the [g1t CLI](/guides/cli/) (`g1t auth login`), or signed in an [AI client](/guides/bring-your-own-agent/) with g1t through MCP. The guide shows the install commands for macOS and Linux and for Windows, ready to copy. | |
| 74 | | **Invite your team** | The workspace has another member, or an invitation waiting for an answer. Workspace invites come with the plan: on a free workspace the step says so, links to the plan, and offers [inviting a friend to g1t](/guides/authentication/#invite-a-friend) instead. | |
| 75 | | **Add a runner** | The workspace has a [self-hosted runner](/guides/self-hosted-runners/), such as [the desktop app](/guides/desktop/). | |
| 76 | |
| 77 | Every step but the AI provider can be skipped with **Skip for now**; a |
| 78 | skipped step counts as settled, and **Don't skip** takes it back. When |
| 79 | every step is done or skipped, the guide says **All set**, and **Finish** |
| 80 | puts it away. |
| 81 | |
| 82 | Closing the guide puts it away too: it stops opening by itself for you, |
| 83 | in this workspace, on every device. Nothing else changes. Open it again |
| 84 | any time from the **Getting started** button at the top of Home, from |
| 85 | **Settings → General** (**Getting started**), from the |
| 86 | workspace's **AI** page, or by typing *Getting started* in the command |
| 87 | palette, which opens Home with `?setup=1`. Each owner has their own: |
| 88 | closing it does not close it for anyone else. |
| 89 | |
| 90 | Members who are not owners do not see it. |
| 91 | |
| 92 | From the API, `GET /workspaces/{workspace}/onboarding` says whether you |
| 93 | dismissed it (`dismissed_at`) and which steps you skipped (`skipped`), and |
| 94 | `PATCH /workspaces/{workspace}/onboarding` changes them: `dismissed` |
| 95 | true puts it away, false makes it open by itself again, and `skipped` |
| 96 | replaces the skipped steps (any of `ai`, `ask`, `code`, `harness`, |
| 97 | `people`, `runner`). Whether a step is done is not stored: it is read from |
| 98 | the workspace each time. |
| 99 | |
| 100 | ```sh |
| 101 | curl -X PATCH https://api.g1t.sh/workspaces/acme/onboarding \ |
| 102 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 103 | -H "Content-Type: application/json" \ |
| 104 | -d '{"dismissed": true}' |
| 105 | ``` |
| 106 | |
| 107 | Reading it takes a token with `workspace:read`; changing it, which |
| 108 | changes only your own, takes `account:write`. |
| 109 | |
| 110 | ## Display name, slug and icon |
| 111 | |
| 112 | A workspace has two names: |
| 113 | |
| 114 | | | Example | Where it appears | Changes | |
| 115 | | --- | --- | --- | --- | |
| 116 | | **Display name** | `Flagon Industries` | The sidebar, the top of its page, mission control and link previews | Any time, up to 80 characters; spaces and capitals are fine | |
| 117 | | **Slug** | `flagon` | Every address: `g1t.sh/flagon/<repo>`, clone URLs, API paths and `g1t.page` app addresses | By an owner, once a day at most; the old one redirects for 90 days. See [rename a workspace](#rename-a-workspace) | |
| 118 | |
| 119 | Without a display name, the slug is shown. Where an address is shown, the |
| 120 | slug is in monospace beside the name. Owners change the display name and |
| 121 | description (up to 160 characters) on **Settings → General**, or with |
| 122 | [`PATCH /workspaces/{workspace}`](/reference/api/workspaces/update-workspace/) |
| 123 | (MCP: `workspace` `update`), which takes `name` and `description` and |
| 124 | changes only the fields given. It needs the `workspace:admin` scope, and |
| 125 | is recorded in the [audit log](/guides/audit-log/): |
| 126 | |
| 127 | ```sh |
| 128 | curl -X PATCH https://api.g1t.sh/workspaces/flagon \n -H "Authorization: Bearer $G1T_TOKEN" \n -H "Content-Type: application/json" \n -d '{"name": "Flagon Industries", "description": "Rockets, and the software that flies them."}' |
| 129 | ``` |
| 130 | |
| 131 | Neither changes the slug; that is a [rename](#rename-a-workspace). |
| 132 | |
| 133 | A workspace also has an icon. Without |
| 134 | one, g1t draws its first letter in a colour of its own. To upload one, an |
| 135 | owner opens **Settings → General** and picks an image: |
| 136 | |
| 137 | - PNG, JPEG, WebP or GIF, at most 1 MB. Square images look best. |
| 138 | - An image is checked by its contents, not its name. SVG is refused, |
| 139 | because it can carry script. |
| 140 | - **Remove** goes back to the letter. |
| 141 | |
| 142 | The icon then shows wherever the workspace does, and on its link previews |
| 143 | (PNG and JPEG icons only). Each image is served from |
| 144 | `g1tusercontent.com/avatars/<sha256>`, an address named after its contents, so an icon |
| 145 | that changes gets a new address and nothing shows the old one. |
| 146 | |
| 147 | You can upload a picture of yourself the same way, under |
| 148 | [Settings → Profile](https://g1t.sh/settings/profile). |
| 149 | |
| 150 | ## Rename a workspace |
| 151 | |
| 152 | Renaming changes the slug, the first part of every address under the |
| 153 | workspace. The display name is separate; change it on its own under |
| 154 | **Settings → General → Workspace details**. Only owners can rename a |
| 155 | workspace. |
| 156 | |
| 157 | 1. Open the workspace's **Settings → General** and go to **Address**. |
| 158 | 2. Type the new slug. The field shows the new address, `g1t.sh/<new>`, and |
| 159 | whether the name is available. |
| 160 | 3. Choose **Change address**, read what changes, type the new slug to |
| 161 | confirm, and choose **Change address** again. |
| 162 | |
| 163 | You land on the workspace's settings at its new address. Repositories, |
| 164 | work items and the rest move with it within a few seconds. |
| 165 | |
| 166 | ### What changes |
| 167 | |
| 168 | | | Before | After | |
| 169 | | --- | --- | --- | |
| 170 | | Pages | `g1t.sh/old/<repo>` | `g1t.sh/new/<repo>` | |
| 171 | | Git remotes | `https://g1t.sh/old/<repo>.git` | `https://g1t.sh/new/<repo>.git` | |
| 172 | | API paths | `https://api.g1t.sh/repos/old/<repo>` | `https://api.g1t.sh/repos/new/<repo>` | |
| 173 | | MCP tool arguments | `"owner": "old"` | `"owner": "new"` | |
| 174 | | Production apps | `https://<project>-old.g1t.page` | `https://<project>-new.g1t.page` | |
| 175 | | Previews | `https://<project>-git-<branch>-old.g1t.page` | `https://<project>-git-<branch>-new.g1t.page` | |
| 176 | |
| 177 | These stay the same: the display name, description and icon, members and |
| 178 | roles, access tokens, secrets and variables, integrations, webhooks, |
| 179 | work items and pull requests, and billing, plans and credit. |
| 180 | |
| 181 | ### What redirects, and for how long |
| 182 | |
| 183 | For 90 days after a rename, the old name keeps working: |
| 184 | |
| 185 | | | Behaviour | |
| 186 | | --- | --- | |
| 187 | | Web pages | Answer with a permanent redirect (301) to the same page under the new name, query string included. | |
| 188 | | `git clone`, `fetch`, `pull` and `push` | Redirected to the new remote. Git follows it, but prints a warning each time until you update the remote. | |
| 189 | | API and MCP | A call that names the old slug runs under the new one. | |
| 190 | | `g1t.page` apps | Production and preview addresses under the old name redirect to the new ones. | |
| 191 | |
| 192 | Update your remotes now rather than relying on the redirect: |
| 193 | |
| 194 | ```sh |
| 195 | git remote set-url origin https://g1t.sh/<new>/<repo>.git |
| 196 | ``` |
| 197 | |
| 198 | Update anything else that has the old name written into it, too: links in |
| 199 | READMEs and docs, CI configuration, API clients and MCP clients. |
| 200 | |
| 201 | ### Limits |
| 202 | |
| 203 | - A workspace can be renamed once every 24 hours. |
| 204 | - For 90 days the old name is held for the workspace. Nobody else can take |
| 205 | it, and you can rename back to it. |
| 206 | - After 90 days the redirects stop, and anyone can create a workspace or |
| 207 | register a username with the old name. Links and remotes that still use |
| 208 | it then reach whatever has the name, or nothing. |
| 209 | - The new name follows the same rules as a new workspace: lowercase letters, |
| 210 | digits and single hyphens, up to 39 characters, not a reserved word or a |
| 211 | well-known GitHub action owner's name (such as `actions` or `docker`), and |
| 212 | not another workspace's slug or someone else's username. |
| 213 | |
| 214 | ## Workspace aliases |
| 215 | |
| 216 | An alias is a second name for a workspace that leads to it for good, |
| 217 | wherever a workspace's name goes. On g1t.sh, `g1t` is an alias of |
| 218 | `flagon-io`, the workspace of Flagon, Inc., which builds g1t and holds its |
| 219 | repositories: `g1t.sh/g1t/deploy` is the repository `flagon-io/deploy`. |
| 220 | |
| 221 | | | Behaviour | |
| 222 | | --- | --- | |
| 223 | | Web pages | Answer with a permanent redirect (301) to the same page under the workspace's slug, query string included. | |
| 224 | | `git clone`, `fetch`, `pull` and `push` | Answered in place, as the repository under the workspace's slug, with the same permissions, and no redirect for git to warn about. | |
| 225 | | API and MCP | A call that names the alias runs under the workspace's slug, and the answer names the workspace by its slug. A token that reaches one repository reaches it under the alias too, and nothing else. | |
| 226 | | Packages | Registry addresses under the alias redirect to the workspace's. | |
| 227 | | Actions | `uses: g1t/deploy@v1` and `g1t/workflows/.g1t/workflows/deploy.yml@v1` are found as `flagon-io/deploy` and `flagon-io/workflows`. See [g1t's own actions](/guides/actions/#g1ts-own-actions). | |
| 228 | |
| 229 | An alias resolves whatever its case (`G1T` is `g1t`), and follows the |
| 230 | workspace through renames: it points at the workspace, not at its slug. |
| 231 | Pages, API answers and links always show the workspace's own slug. |
| 232 | |
| 233 | An alias never changes who can see what. A private repository is found |
| 234 | under the alias only by someone who could see it under the workspace's |
| 235 | slug, and the alias gives nobody access they did not have. |
| 236 | |
| 237 | Aliases are set and removed by g1t's staff; there is no setting for them. |
| 238 | While an alias exists, nobody can register it as a username, create a |
| 239 | workspace with it, or rename a workspace to it. An alias is never a |
| 240 | person's or a workspace's name, and never one of the site's own routes. |
| 241 | [Contact us](https://g1t.sh/support) if your workspace needs one, such as |
| 242 | for a name it used to trade under. |
| 243 | |
| 244 | ## Data residency |
| 245 | |
| 246 | Data residency says where the git data of the workspace's new repositories |
| 247 | is stored. The section appears in **Settings** once g1t can store |
| 248 | repositories in the EU. Until then it is not shown, and every repository is |
| 249 | stored wherever g1t stores repositories. |
| 250 | |
| 251 | | Setting | What it does | |
| 252 | | --- | --- | |
| 253 | | Anywhere | New repositories are stored wherever g1t stores repositories. The default. | |
| 254 | | EU only | New repositories are stored in the EU. If EU storage cannot take one right now, the repository is not made, and you are told why. It is never stored somewhere else instead. | |
| 255 | |
| 256 | To change it: |
| 257 | |
| 258 | 1. Open the workspace, then **Settings**. Only owners see the page. |
| 259 | 2. Under **Data residency**, choose **Anywhere** or **EU only**. |
| 260 | 3. Select **Save**. |
| 261 | |
| 262 | The setting applies to repositories made after you save it, however they |
| 263 | are made: from the site, with the API, by pushing to a new address, or by |
| 264 | importing. Repositories the workspace already has stay where they are. To |
| 265 | move them, contact support; a move keeps each repository's address, history |
| 266 | and settings, and pushes to it wait a few minutes while it happens. |
| 267 | |
| 268 | Data residency covers the git data: commits, branches, tags and files, |
| 269 | including pull requests' working copies, which are stored with their |
| 270 | repository. Work items, pull requests, comments and settings are not affected. |
| 271 | A repository [transferred](/guides/transferring-repositories/) to another |
| 272 | workspace stays where it is stored. |
| 273 | |
| 274 | Changing the setting is recorded in the |
| 275 | [audit log](/guides/audit-log/) as `workspace.residency_changed`. |
| 276 | |
| 277 | ## Delete a workspace |
| 278 | |
| 279 | Deleting a workspace takes everything in it with it, in one step: its |
| 280 | repositories, projects, apps, members' access and tokens. Only an owner can, |
| 281 | signed in as a person, typing the workspace's slug to confirm. |
| 282 | |
| 283 | It is not gone at once. For **30 days** g1t keeps all of it, so that a |
| 284 | deletion you did not mean, or did not make, can be undone: an owner writes |
| 285 | to support@g1t.sh, and support restores the workspace as it was. After 30 |
| 286 | days it is purged for good. |
| 287 | |
| 288 | 1. Open the workspace's **Settings → General** and go to **Danger zone**. |
| 289 | It lists what will go with the workspace: its repositories, projects, |
| 290 | live apps and members. |
| 291 | 2. Choose **Delete workspace**, read what happens, type the workspace's |
| 292 | slug to confirm, and choose **Delete workspace** again. You are taken |
| 293 | back to your own home. |
| 294 | |
| 295 | The one thing that can stand in the way is billing: see |
| 296 | [what billing needs](#what-billing-needs). Repositories you want to keep in |
| 297 | another workspace, [transfer](/guides/transferring-repositories/) first; |
| 298 | their old addresses keep redirecting after the workspace is gone. |
| 299 | |
| 300 | From the API, call |
| 301 | [`DELETE /workspaces/{workspace}`](/reference/api/workspaces/delete-workspace/) |
| 302 | with the slug in `confirm`; over MCP, the `workspace` tool's `delete` |
| 303 | action. |
| 304 | |
| 305 | Some workspaces can never be deleted, by anyone, such as Flagon's, which |
| 306 | runs g1t. Their Danger zone says so instead of offering the button. |
| 307 | |
| 308 | ### What billing needs |
| 309 | |
| 310 | | | | |
| 311 | | --- | --- | |
| 312 | | Money owed | Charged to the workspace's card at once, with no minimum charge. With no card, add one or pay from **Billing** first. | |
| 313 | | An unpaid invoice | Pay it from **Billing** first. | |
| 314 | | Prepaid credit | It would be lost: spend it, or write to support@g1t.sh about a refund, first. | |
| 315 | | Usage this month still being metered | Storage and git operations are charged when the month closes. You can delete the workspace from the 1st of next month. | |
| 316 | | The g1t plan | Ends at Stripe at once, not at the end of the period. | |
| 317 | | An enterprise account | A workspace billed through one is moved off it by g1t first: write to support@g1t.sh. | |
| 318 | |
| 319 | A comped workspace owes nothing; only its plan is ended. |
| 320 | |
| 321 | ### What happens |
| 322 | |
| 323 | At once, when an owner deletes it: |
| 324 | |
| 325 | | | | |
| 326 | | --- | --- | |
| 327 | | Members | Lose access, and the workspace leaves their list. Their own accounts are not touched: a person with no workspace left can still sign in, and create or join one. | |
| 328 | | Access tokens | The workspace's own tokens stop working. Personal tokens are not affected. | |
| 329 | | Repositories | Deleted with it: git refuses them, and their pages answer 404. Workflow runs stop. Ones deleted on their own earlier stay deleted. | |
| 330 | | Projects and apps | Hidden. Its apps are taken offline and nothing builds. Custom domains are kept for a restore. | |
| 331 | | Its pages | Answer 404, and it drops out of search. | |
| 332 | | Billing | What it owes is charged, and its plan ends, as [billing needs](#what-billing-needs). Nothing more is charged. | |
| 333 | | The audit log | Records the deletion. | |
| 334 | |
| 335 | Within 30 days, support can restore it: its members, tokens, repositories, |
| 336 | projects and apps come back as they were, and its apps go back up as its |
| 337 | limit allows. Its plan does not come back by itself: an owner starts it |
| 338 | again from **Billing**. A repository deleted on its own before the |
| 339 | workspace was stays in **Recently deleted**. |
| 340 | |
| 341 | After 30 days it is purged: |
| 342 | |
| 343 | | | | |
| 344 | | --- | --- | |
| 345 | | Repositories | Purged, their git data with them, including any that were in Recently deleted. | |
| 346 | | Projects, apps and custom domains | Removed. | |
| 347 | | Webhooks, integrations, secrets and variables | The workspace's own are removed. | |
| 348 | | Guardrails | The workspace's own are removed. | |
| 349 | | Statements, invoices and the ledger | Kept, for accounting. | |
| 350 | | The audit log | Kept as [long as its account keeps it](/guides/audit-log/#how-long-it-is-kept), with the purge as its last entry: once the plan ends with the workspace, that is 7 days, unless an enterprise pays for it or longer was arranged. With no owners left, ask support@g1t.sh for an export. | |
| 351 | | Old addresses | Redirects for repositories transferred out keep working. The workspace's own pages answer 404. | |
| 352 | |
| 353 | ### The name afterwards |
| 354 | |
| 355 | A deleted workspace's slug is never given to another workspace or used as |
| 356 | someone else's username. While it can still be restored, the slug is held |
| 357 | for it. Links and git remotes that still use it keep |
| 358 | meaning what they meant: a transferred repository's old address keeps |
| 359 | redirecting to it, and nobody can take the name in the meantime. |
| 360 | |
| 361 | The one exception: when the slug is your own username, you may create a |
| 362 | workspace with that name again once the old one is purged. It starts empty, on standard billing terms, |
| 363 | and a repository made in it at an old address ends that address's redirect. |
| 364 | |
| 365 | ## Members and roles |
| 366 | |
| 367 | <a id="members-and-owners"></a> |
| 368 | |
| 369 | | Role | Can | |
| 370 | | --- | --- | |
| 371 | | Member | Create repositories (as the [member privileges](#member-privileges) allow), see the workspace's usage and billing, and get the workspace's [base permission](/guides/access-and-roles/#the-base-permission) on every repository in it: Read for a new workspace, which an owner can raise to Write to let members push and merge pull requests. Admin on the repositories they create. | |
| 372 | | Owner | Everything a member can, and manage members and owners, the base permission, the member privileges, two-factor requirement, the workspace's access tokens, its details, and billing: the plan, card checks, prepayment and limits. Admin on every repository, and the only ones who can transfer and delete them unless the member privileges allow admins; see [access and roles](/guides/access-and-roles/). | |
| 373 | |
| 374 | A workspace can have any number of owners, and always has at least one. |
| 375 | |
| 376 | ### Roles that add to a member |
| 377 | |
| 378 | An owner can give a member one or both of these roles. Each adds to what |
| 379 | the member already has; an owner has both already. |
| 380 | |
| 381 | | Role | Adds | |
| 382 | | --- | --- | |
| 383 | | **Billing manager** | Manages the workspace's billing as an owner does: the plan, budget and spend limit, prepaying, the card, billing details and invoices. Gives nothing on repositories. | |
| 384 | | **Security manager** | Read on every repository, and seeing and managing every security alert and security setting on them: dismissing and reopening alerts, custom patterns, reviewing push protection bypass requests, and the workspace's security settings. | |
| 385 | |
| 386 | ### Change someone's role |
| 387 | |
| 388 | On **Members**, `g1t.sh/<workspace>/-/members` (**Workspace → Access → |
| 389 | Members**), an owner opens the **⋯** menu beside a member: |
| 390 | |
| 391 | 1. **Make owner** or **Make member** changes their role. |
| 392 | 2. **Billing manager** and **Security manager** turn each role on or off. |
| 393 | 3. **Transfer ownership…** hands the workspace to that member: they become |
| 394 | an owner and you a member, in one step. To add an owner without stepping |
| 395 | down, choose **Make owner** instead. |
| 396 | 4. **Remove from {workspace}…** takes them out. Their roles on its |
| 397 | repositories and their place in its teams go too. |
| 398 | |
| 399 | Owners see a shield beside each member: green when two-factor |
| 400 | authentication is on, amber when it is off. Above the list, a search box |
| 401 | finds a member by username or name, and the filters narrow the list by |
| 402 | role, by two-factor authentication (owners only) and by team; each is kept |
| 403 | in the address (`?q=`, `?role=`, `?2fa=`, `?team=`), so a filtered list can |
| 404 | be shared. |
| 405 | |
| 406 | The last owner cannot be made a member, removed, or leave: make someone |
| 407 | else an owner first, or [delete the workspace](#delete-a-workspace). |
| 408 | |
| 409 | ### Leave a workspace |
| 410 | |
| 411 | Anyone can leave a workspace they belong to: at the bottom of **Members**, |
| 412 | choose **Leave {workspace}** and confirm. Your roles on its repositories |
| 413 | and your place in its teams go with you at once. The only owner cannot |
| 414 | leave. |
| 415 | |
| 416 | ### Add people |
| 417 | |
| 418 | Whoever creates a workspace is its owner. Nobody is added to a workspace |
| 419 | without saying yes: an owner invites people, and each person accepts or |
| 420 | declines. |
| 421 | |
| 422 | Anyone can make a g1t account without an invite, so to bring someone in |
| 423 | you invite them to the workspace; someone without an account signs up from |
| 424 | the invitation. To tell a friend about g1t without adding them to a |
| 425 | workspace, use [Invite a friend](/guides/authentication/#invite-a-friend) |
| 426 | in your account menu instead. |
| 427 | |
| 428 | On the workspace's **Members** page, `g1t.sh/<workspace>/-/members` |
| 429 | (**Workspace → Access → Members** in the sidebar), or on **Invitations** |
| 430 | beside it: |
| 431 | |
| 432 | 1. Select **Invite**. A dialog opens. |
| 433 | 2. Under **Who**, type a username, a name or an email address. As you |
| 434 | type, people on g1t are offered by username and name, with their |
| 435 | pictures; hover over one for their card. Only usernames, names and |
| 436 | pictures are shown, never anyone's email address. An email address is |
| 437 | taken as written. |
| 438 | 3. Choose the **Role** they join with: **Member** or **Owner**. |
| 439 | 4. Write a **Message** if you like: a line quoted in the invitation email, |
| 440 | under your name. Up to 500 characters. |
| 441 | 5. Select **Invite**. The dialog closes and the page says who was invited. |
| 442 | |
| 443 | - **By username**: they get a |
| 444 | [workspace invitation](/guides/authentication/#workspace-invitations) in |
| 445 | their notifications and by email, and join with that role when they accept at |
| 446 | [g1t.sh/invitations](https://g1t.sh/invitations). If they decline, you |
| 447 | are told in your notifications. It costs nothing. |
| 448 | - **By email address**: g1t emails an invite that only that address can |
| 449 | use. With a g1t account, it is a workspace invitation like the one above |
| 450 | and costs nothing. Without one, the invitation also lets them make the |
| 451 | account first, and costs nothing (see |
| 452 | [invites](/guides/authentication/#invites)). The new account is then |
| 453 | invited to the workspace, and joins when it accepts. The page never says which it was. |
| 454 | |
| 455 | The email names you and the workspace and links to the invite's page. |
| 456 | Someone new signs up right there, with the invited address filled in; once |
| 457 | the address is confirmed (straight away when they opened the page from |
| 458 | that email, which proves the address is theirs, otherwise with the code g1t |
| 459 | emails them), they are asked to accept or decline the invitation. Someone |
| 460 | with an account signs in and accepts on the page. Accepting lands them in |
| 461 | the workspace, with a one-time welcome. See |
| 462 | [using an invite](/guides/authentication/#using-an-invite). |
| 463 | |
| 464 | #### When someone joins |
| 465 | |
| 466 | A person becomes a member by accepting an invitation or by using an |
| 467 | invite code that names the workspace. The join is an event, |
| 468 | `workspace.member_joined`, for the workspace's |
| 469 | [webhooks](/guides/webhooks/#events). |
| 470 | |
| 471 | Every invitation sent is on **Invitations**, |
| 472 | `g1t.sh/<workspace>/-/members/invitations` (**Workspace → Access → |
| 473 | Invitations**, owners only): a table of who it is for, who sent it, the |
| 474 | role, when it was sent and where it stands, newest first. The chips above |
| 475 | it narrow the table, each with its count: |
| 476 | |
| 477 | | Chip | Shows | |
| 478 | | --- | --- | |
| 479 | | **All** | Every invitation, however it ended. | |
| 480 | | **Pending** | The ones still waiting: to be used, for the new account to confirm its email, or for the person to accept. Each says the day it stops working (30 days after it was sent). | |
| 481 | | **Accepted** | The people who joined. | |
| 482 | | **Declined** | The people who said no. | |
| 483 | | **Expired** | The ones nobody used in time. g1t does not yet know whether an invitation's email was delivered, so one that bounced ends up here too. | |
| 484 | | **Revoked** | The ones an owner took back. | |
| 485 | |
| 486 | The **⋯** menu on a pending invitation has **Copy link** (the invitation's |
| 487 | page, while it waits to be used), **Send again** (the same email, and the |
| 488 | inbox notice again for someone on g1t; the invitation itself does not |
| 489 | change) and **Revoke**. Through the API, the invitation is sent again with |
| 490 | nothing yet; revoke it and invite again instead. Converting an outside |
| 491 | collaborator to a member sends them an invitation the same way. The |
| 492 | Members page says how many invitations are waiting, and leads here. |
| 493 | Through the API, use |
| 494 | [`POST /workspaces/{workspace}/invitations`](/reference/api/invites/invite-member/) |
| 495 | with a `username` or an `email` and a `role` (the `workspace` tool's |
| 496 | `invite_member` action over MCP); the person answers with |
| 497 | [`POST /user/invitations/{id}/accept`](/reference/api/invites/accept-invitation/) |
| 498 | or [`/decline`](/reference/api/invites/decline-invitation/). |
| 499 | |
| 500 | To give someone a role on one repository without making them a member, |
| 501 | add them as an [outside collaborator](/guides/access-and-roles/#outside-collaborators). |
| 502 | |
| 503 | **A free workspace cannot add people.** Until it starts the g1t plan, it |
| 504 | cannot add members, send invites, or invite outside collaborators, and an |
| 505 | invite sent before waits until the plan is on. Its members stay. Members and |
| 506 | Invitations show **Start the plan to invite people** with the button in place of |
| 507 | **Invite**, and the API and MCP answer `402` (`payment_required`). See |
| 508 | [who a free workspace can add](/guides/usage-and-billing/#who-a-free-workspace-can-add). |
| 509 | |
| 510 | ### Members through the API |
| 511 | |
| 512 | | Route | MCP tool and action | What it does | Who | |
| 513 | | --- | --- | --- | --- | |
| 514 | | `GET /workspaces/{workspace}/members` | `workspace` `list_members` | Its members, owners first: `role` (`owner` or `member`), `org_roles` (`billing_manager`, `security_manager`) and, for owners, `two_factor`. | Members | |
| 515 | | `PATCH /workspaces/{workspace}/members/{username}` | `workspace` `update_member` | Change `role` and `org_roles` (a list that replaces theirs). | Owners | |
| 516 | | `DELETE /workspaces/{workspace}/members/{username}` | `workspace` `remove_member` | Remove someone. Your own username is leaving. | Owners | |
| 517 | | `POST /workspaces/{workspace}/transfer_ownership` | `workspace` `transfer_ownership` | Hand it to `username`: they become an owner, you a member. | Owners | |
| 518 | | `DELETE /user/memberships/{workspace}` | `workspace` `leave` | Leave it. | You | |
| 519 | |
| 520 | Each is for people, signed in or with a personal access token; never a |
| 521 | workspace token. A change that would leave no owner answers `409`. |
| 522 | |
| 523 | ```sh |
| 524 | curl -X PATCH https://api.g1t.sh/workspaces/acme/members/grace \ |
| 525 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 526 | -d '{"org_roles": ["security_manager"]}' |
| 527 | ``` |
| 528 | |
| 529 | ## Member privileges |
| 530 | |
| 531 | What members can do beyond their role on each repository. Owners set them |
| 532 | under **Workspace → Access → [Permissions](/guides/permissions/#code)**, |
| 533 | `g1t.sh/<workspace>/-/permissions`, in the **Code** card, and can always do |
| 534 | all of it themselves. |
| 535 | |
| 536 | | Setting | Default | When on | |
| 537 | | --- | --- | --- | |
| 538 | | **Members can create public repositories** (`members_can_create_public_repositories`) | On | Any member can create a public repository. | |
| 539 | | **Members can create private repositories** (`members_can_create_private_repositories`) | On | Any member can create a private repository. | |
| 540 | | **Repository admins can change visibility** (`members_can_change_repo_visibility`) | On | A member with Admin on a repository can make it public or private, if they could create one of that kind. | |
| 541 | | **Repository admins can delete and transfer repositories** (`members_can_delete_repositories`) | Off | A member with Admin on a repository can delete it, or transfer it to a workspace where they can create one. | |
| 542 | | **Repository admins can add outside collaborators** (`members_can_invite_outside_collaborators`) | On | A member with Admin on a repository can give a role on it to someone outside the workspace. | |
| 543 | |
| 544 | When one is off, only owners can do it; the refusal says so. Someone who is |
| 545 | not a member, an outside collaborator with Admin, never gets these. |
| 546 | Forking private repositories is not a setting: g1t has no personal forks |
| 547 | to allow or refuse. |
| 548 | |
| 549 | Through the API, `GET /workspaces/{workspace}` returns each by its name, |
| 550 | and [`PATCH /workspaces/{workspace}`](/reference/api/workspaces/update-workspace/) |
| 551 | sets any of them (`workspace` `update` over MCP). Each change is in the |
| 552 | [audit log](/guides/audit-log/) as `workspace.member_privileges_changed`. |
| 553 | |
| 554 | ## Workflows the workspace manages |
| 555 | |
| 556 | An owner can run a workflow in every repository of the workspace, or in |
| 557 | those whose names match, without committing it to each: a security scan, a |
| 558 | licence check, a release policy. Add it under **Workspace → Code → |
| 559 | Actions**, `g1t.sh/<workspace>/-/actions`, from a workflow file in one of |
| 560 | the workspace's repositories, as **Required** (repositories cannot take its |
| 561 | place or turn it off, so a ruleset can require its check) or **Default** |
| 562 | (a repository's own workflow of the same name runs instead, and its admins |
| 563 | can turn it off). Each repository's Actions page lists it as managed by the |
| 564 | workspace. [Workflows a workspace manages](/guides/actions/#workflows-a-workspace-manages) |
| 565 | has the details, and the API. |
| 566 | |
| 567 | ## Require two-factor authentication |
| 568 | |
| 569 | An owner can require everyone with access to the workspace, its members |
| 570 | and its outside collaborators, to have |
| 571 | [two-factor authentication](/guides/authentication/#two-factor-authentication) |
| 572 | on. |
| 573 | |
| 574 | 1. Turn it on for your own account first. |
| 575 | 2. Open **Workspace → General**, `g1t.sh/<workspace>/-/settings#two-factor`. |
| 576 | Under **Authentication security**, it says how many members do not have |
| 577 | it on, and who. |
| 578 | 3. Turn on **Require two-factor authentication** and choose **Save**. |
| 579 | |
| 580 | From then on, someone without it keeps their place but cannot use the |
| 581 | workspace: its private repositories, pages and API answer as if they were |
| 582 | not a member, and every page shows them a notice with a link to turn it |
| 583 | on. Turning it on gives everything back at once. Nobody can join or accept |
| 584 | an invitation to the workspace without it. |
| 585 | |
| 586 | Through the API, `two_factor_requirement_enabled` on |
| 587 | `PATCH /workspaces/{workspace}`. Recorded as `workspace.two_factor_required` |
| 588 | and `workspace.two_factor_not_required`. |
| 589 | |
| 590 | A workspace on a paid plan can also require |
| 591 | [single sign-on](/guides/single-sign-on/) through its own identity |
| 592 | provider. |
| 593 | |
| 594 | ## The workspace's page |
| 595 | |
| 596 | A workspace's own page, `g1t.sh/<workspace>`, has its icon, name, address |
| 597 | and description at the top, then its overview: your |
| 598 | [pinned projects](#pinned-and-recent-projects), then the most active ones, |
| 599 | the pull requests in progress across them, and **All projects**. Members |
| 600 | also see a **Usage** card with this month's spend, and who belongs. |
| 601 | |
| 602 | The workspace's other pages each have a heading of their own and a row in |
| 603 | [the sidebar](#the-sidebar), lit while you are on them. The trail in the |
| 604 | top bar, such as *acme / Projects*, leads back to the workspace's page. |
| 605 | |
| 606 | | Page | Address | Who | | |
| 607 | | --- | --- | --- | --- | |
| 608 | | **Overview** | `g1t.sh/<workspace>` | Everyone | The page above. | |
| 609 | | **Projects** | `/-/projects` | Everyone | Every project you can see. See [the Projects page](#the-projects-page). | |
| 610 | | [**Packages**](/guides/packages/) | `/-/packages` | Everyone | What the workspace publishes. A visitor opens it from **Packages** on the workspace's page. | |
| 611 | | [**Teams**](/guides/teams/) | `/-/teams` | Members | Groups of members given roles on repositories together, mentioned as `@workspace/team` and asked to review together. Each team has its own page at `/-/teams/<team>`. | |
| 612 | | [**People**](/guides/people-and-teams/) | `/-/people` | Members | The workspace's people, with their titles, teams and what they own. Each has a profile at `/-/people/<username>`. | |
| 613 | | **Members and invites** | `/-/members` | Members | Who belongs. Owners invite, change roles and remove people here. | |
| 614 | | **Insights** | `/-/insights` | Members | How the workspace delivers, what waits and what it costs. See [Insights](#insights). | |
| 615 | | **Settings** | `/-/settings` | Owners | How the workspace is set up and connected (below). | |
| 616 | |
| 617 | Each person sees the projects they can read: a member whose base permission |
| 618 | is None, an [outside collaborator](/guides/access-and-roles/#outside-collaborators) |
| 619 | or a visitor sees the public ones and those shared with them, without the |
| 620 | workspace's people, deployments or settings. |
| 621 | |
| 622 | `g1t.sh/<workspace>?tab=projects` (or `repositories`, `packages`, |
| 623 | `teams`, `people`, `members`, `insights` or `settings`) opens that page. |
| 624 | |
| 625 | ### The Projects page |
| 626 | |
| 627 | The Projects page, `g1t.sh/<workspace>/-/projects`, is made for workspaces with hundreds of projects: |
| 628 | |
| 629 | - **Find a project** matches every word you type in a project's name, its |
| 630 | address or its description. Press <kbd>/</kbd> anywhere on the page to |
| 631 | start typing. |
| 632 | - **Filters**: public or private; [what it is](/guides/projects/#what-a-project-is) |
| 633 | (apps, libraries, and tools, docs or other when the workspace has any); the language its |
| 634 | manifests say it is written in; only projects with |
| 635 | [Deployments](/guides/deployments/) on; and archived projects, which are |
| 636 | left out unless you ask for them. Each choice shows how many projects it |
| 637 | holds. |
| 638 | - **Sort** by recently updated (its settings or its last push, whichever is |
| 639 | later), recently pushed, most active, or name. Most active counts each |
| 640 | push, work item or pull request opened or closed, review, comment and |
| 641 | deployment, and what happened a week ago counts half as much. |
| 642 | - **List** or **grid**, 30 projects to a page. |
| 643 | - The arrow keys (or <kbd>j</kbd> and <kbd>k</kbd>) move between projects, |
| 644 | and <kbd>Enter</kbd> opens one. |
| 645 | |
| 646 | Everything you choose is in the address, so a filtered list can be |
| 647 | bookmarked or shared. |
| 648 | |
| 649 | ### Insights |
| 650 | |
| 651 | Insights, `g1t.sh/<workspace>/-/insights`, puts the workspace's projects |
| 652 | side by side: how much they ship, how long changes take, what is waiting |
| 653 | now, and what the work cost. Choose the last 7, 30 or 90 days and all |
| 654 | projects or one; both are in the address (`?period=7d&project=api`). |
| 655 | |
| 656 | | | What it counts | |
| 657 | | --- | --- | |
| 658 | | **Merged changes** | Pull requests merged in the period, with a bar for each day. The daily values are in a table under the chart. | |
| 659 | | **Average lead time** | From a pull request's opening to its merge, for those merged in the period. | |
| 660 | | **Average first review** (per project) | From opening to the first approval or request for changes by a person other than its owner, for first reviews given in the period. Reviews by g1t and by workspace agents do not count. | |
| 661 | | **Opened** and **Open now** (per project) | Pull requests opened in the period, and those open or in draft now. | |
| 662 | | **Awaiting a first review** | Open pull requests (not drafts) no person has reviewed yet. | |
| 663 | | **In the merge queue** | Open pull requests waiting, being tested or passed in the [merge queue](/guides/merge-queue/). | |
| 664 | | **Checks running** and **Checks failed** | Open pull requests by their latest commit's checks: statuses, check runs and g1t Actions jobs, as the pull request shows them. One with a failed check counts as failed, else one with a check still going counts as running; one with no checks counts in neither. | |
| 665 | | **Usage at price** and **Cost** | [Usage](/guides/usage-and-billing/#the-usage-page) at price, before what the plan, credit or discounts paid. A project's cost is its repository's usage; with all projects shown, the total also holds usage that is no project's. | |
| 666 | | **Cost per merged change** | The period's usage divided by its merged changes: an average, not what any one change cost. | |
| 667 | |
| 668 | The days are UTC days, and the waiting counts are as of now and can |
| 669 | overlap. Each person sees only the projects they can read. When part of |
| 670 | it cannot be read, such as one service being briefly unavailable, Insights |
| 671 | says so and shows a dash in place of numbers it cannot vouch for. **Explore |
| 672 | costs** opens [Usage](/guides/usage-and-billing/#the-usage-page) with the same period and project. |
| 673 | |
| 674 | ## The rail, the sidebar and the page |
| 675 | |
| 676 | Signed in, g1t is always about one workspace: the one you are in. On a |
| 677 | workspace's pages, and on a project in one of your workspaces, that is the |
| 678 | workspace the page belongs to, so opening a project in another of your |
| 679 | workspaces switches you to it; anywhere else, even on public pages such as |
| 680 | [Explore](https://g1t.sh/explore), someone's profile or another |
| 681 | workspace's public project, it stays the one you chose last. |
| 682 | |
| 683 | Those pages beyond your workspaces are browsing g1t: the rail lights |
| 684 | **Explore**, and Explore's sidebar sits beside them. It has **Back to** |
| 685 | your workspace at the top, which goes to its [Home](/guides/home/); then |
| 686 | **Recently active**, **New projects** and **Search**; **Your stars** and |
| 687 | **Your profile**; and under **You are viewing**, whose page this is: a |
| 688 | workspace with its overview and **Projects**, or a person with their |
| 689 | profile and **Stars**. In one of their public projects, the sidebar is |
| 690 | that project's own list, as in Code, with **Projects** at its top to go |
| 691 | back to the rest of theirs. A project shared with you stays in Code, under |
| 692 | **Shared with you**. On a phone, the button at the top left opens the same |
| 693 | sidebar, and **More** has **Explore**. |
| 694 | |
| 695 | Each page has three parts: |
| 696 | |
| 697 | | Part | Where | What it holds | |
| 698 | | --- | --- | --- | |
| 699 | | **The rail** | A narrow column of icons down the left edge | g1t's mark, which goes to [Home](/guides/home/); the built-in apps; and at its foot **People**, **Workspace** and your account. Hold the pointer over an icon for its name. | |
| 700 | | **The sidebar** | Flush against the rail | The workspace and its switcher at the top, **Search or jump to**, then the lists of the app you are in, in named groups. Home has none. | |
| 701 | | **The page** | The rest of the window, flat against the sidebar | Its header: the button that shows or hides the sidebar, where you are, **Search or jump to** (<kbd>Ctrl</kbd> <kbd>K</kbd>, or <kbd>⌘</kbd> <kbd>K</kbd> on a Mac) when the sidebar is hidden or has a search of its own, the [notifications](/guides/notifications/) bell and **Create new**. Then the page itself. | |
| 702 | |
| 703 | ### The rail |
| 704 | |
| 705 | The built-in apps are always in the rail, each an icon with what is |
| 706 | unread on it: |
| 707 | |
| 708 | | App | Opens | |
| 709 | | --- | --- | |
| 710 | | **Home** | Where you're needed across the workspace, and what happened while you were away. See [Home](/guides/home/). | |
| 711 | | **Work** | The workspace's work items, with its labels and milestones, at `g1t.sh/<workspace>/-/work`. See [work items](/guides/work-items/). | |
| 712 | | **Chat** | Channels and messages. See [Chat](/guides/chat/). | |
| 713 | | **Notifications** | Reviews, mentions and failures. See [notifications](/guides/notifications/). | |
| 714 | | **Code** | Projects, pull requests and checks. Not shown to a member without Code access. | |
| 715 | | **Artifacts** | Documents, decks and pages. See [artifacts](/guides/artifacts/). | |
| 716 | | **People** | Everyone in the workspace, and its [teams](/guides/teams/). See [people and teams](/guides/people-and-teams/). | |
| 717 | | **Workspace** | The workspace's settings: who has access, money, compute, and how each part of g1t is set up. See [Workspace mode](#workspace-mode). | |
| 718 | |
| 719 | The app you are in sits on a filled square. Your account is the |
| 720 | avatar at the foot: your status, your profile and settings, |
| 721 | [appearance](#appearance), the documentation, support, status, the |
| 722 | keyboard's shortcuts, and signing out. |
| 723 | |
| 724 | ### Appearance |
| 725 | |
| 726 | g1t comes in a dark theme and a light one. Until you choose, it follows |
| 727 | your system's setting. |
| 728 | |
| 729 | | Choice | What you see | |
| 730 | | --- | --- | |
| 731 | | **Auto** | Follows your system's light or dark setting, and changes when it does. | |
| 732 | | **Light** | A near-white page with white panels and a deeper lavender accent. | |
| 733 | | **Dark** | g1t's very dark gray with the lavender accent. | |
| 734 | |
| 735 | To change it: |
| 736 | |
| 737 | 1. Select your avatar at the foot of the rail. On a phone, open **More**, |
| 738 | then **You and help**. |
| 739 | 2. Under **Appearance**, select **Auto** (the screen icon), **Light** (the |
| 740 | sun) or **Dark** (the moon). |
| 741 | |
| 742 | The page changes at once. You can also choose under |
| 743 | [Settings → Account](https://g1t.sh/settings/account), or press |
| 744 | <kbd>Ctrl</kbd> <kbd>K</kbd> (<kbd>⌘</kbd> <kbd>K</kbd> on a Mac) and run |
| 745 | **Use light theme**, **Use dark theme** or **Use auto theme**. Signed out, |
| 746 | the same commands are in ⌘K, and the phone's menu has the switch. |
| 747 | |
| 748 | Your choice is kept in this browser, in a `g1t_theme` cookie, so every page |
| 749 | is drawn in it from the start; another browser or device starts on Auto. |
| 750 | Product screenshots on g1t.sh's home page stay dark in either theme. |
| 751 | |
| 752 | These docs and [status.g1t.sh](https://status.g1t.sh/) also follow your |
| 753 | system's setting, each with its own switch for this browser: here, the |
| 754 | **Auto**, **Light** and **Dark** menu at the end of the header (at the foot |
| 755 | of the menu on a phone); on the status page, the three icons at the top. |
| 756 | |
| 757 | ### Developer mode |
| 758 | |
| 759 | When a page fails, g1t says only that something went wrong. To see why, |
| 760 | turn on **Developer mode** under |
| 761 | [Settings → Account](https://g1t.sh/settings/account#developer). From then |
| 762 | on, a page that fails shows the error itself: its message and stack, the |
| 763 | address, the time, the routes the page was drawn from, the site's build |
| 764 | and your browser (and the desktop app's version, inside it). **Copy |
| 765 | details** copies all of it as one report, ready to paste into a support |
| 766 | request or a bug report. |
| 767 | |
| 768 | Signed in, errors from g1t's side come through in full too, where |
| 769 | otherwise they read *Unexpected Server Error*. They are only ever about |
| 770 | your own requests. Like Appearance, the setting is kept in this browser, in |
| 771 | a `g1t_dev` cookie; turn it off the same way. |
| 772 | |
| 773 | ### The sidebar |
| 774 | |
| 775 | The sidebar's top row names the workspace you are in. Select it to switch |
| 776 | to another of your workspaces, make a new one, or open your profile or |
| 777 | settings. The button beside it hides the sidebar, leaving the rail alone |
| 778 | and the page wider, and the same button at the left of the page's header |
| 779 | brings it back; <kbd>Ctrl</kbd> <kbd>B</kbd> (<kbd>⌘</kbd> <kbd>B</kbd> on |
| 780 | a Mac) does both, except while you type. g1t remembers which you chose. |
| 781 | When the sidebar is hidden, or the app has none, the page's header starts |
| 782 | with the same switcher. Under the top row, **Search or jump to** opens the |
| 783 | same palette as <kbd>Ctrl</kbd> <kbd>K</kbd>; in Chat and Artifacts, whose |
| 784 | sidebars search their own lists, it stays in the page's header. |
| 785 | |
| 786 | Below it are the lists of the app you are in, each group under a small |
| 787 | heading. Code's lists the workspace's |
| 788 | [projects](#pinned-and-recent-projects), and drills into a project's own |
| 789 | list when you open one, with **‹ All projects** at the top to go back. Its |
| 790 | **Settings** opens one level further: **General**, **Deployments**, |
| 791 | **Domains**, **Guardrails**, **Repository**, **Access**, |
| 792 | **Branches and merging**, **Secrets and variables** and **Webhooks**, each |
| 793 | for the roles that can use it. A link straight to any of these pages opens |
| 794 | the sidebar already there. |
| 795 | |
| 796 | Workspace's sidebar is the [workspace's settings area](#workspace-mode): |
| 797 | its **Overview**, then every settings page in named groups, each one click |
| 798 | away. |
| 799 | |
| 800 | Below 1024px wide, the sidebar opens over the page from the left, from the |
| 801 | header's button, and closes when you open a page. |
| 802 | |
| 803 | ### Workspace mode |
| 804 | |
| 805 | **Workspace**, at the foot of the rail, is everything about the workspace |
| 806 | itself: who has access, what it spends, and how each part of g1t is set up |
| 807 | for it. There is no second Settings inside it: every page is in the |
| 808 | sidebar, under the group it belongs to, and the group you are in stays |
| 809 | open while the others fold when you select their name. A page only owners |
| 810 | open is left out for members. |
| 811 | |
| 812 | | Group | Page | Who | | |
| 813 | | --- | --- | --- | --- | |
| 814 | | | **Overview** | Members | The workspace at a glance: members, plan and spend. `g1t.sh/<workspace>/-/workspace` | |
| 815 | | **General** | **General** | Owners | The icon, the display name, a one-line description, the address (the slug), [requiring two-factor authentication](#require-two-factor-authentication), [data residency](#data-residency), and deleting the workspace. `-/settings` | |
| 816 | | **Access** | **Members** | Members | Who is in the workspace and their roles, with search and filters; owners [invite people](#add-people), change roles, and see **Outside collaborators**. `-/members` | |
| 817 | | | **Invitations** | Owners | Every invitation to join, filtered by where it stands; send one again, revoke it, copy its link. `-/members/invitations` | |
| 818 | | | [**Permissions**](/guides/permissions/) | Owners | Who may do what, part by part: the base permission, repositories, teams and chat. `-/permissions` | |
| 819 | | | [**Single sign-on**](/guides/single-sign-on/) | Owners | Your identity provider over SAML 2.0, OpenID Connect or OAuth 2.0, the people linked to it, and requiring it. Every paid plan. `-/sso` | |
| 820 | | | [**Access tokens**](#workspace-access-tokens) | Members | The workspace's own tokens. Owners create and delete them. `-/tokens` | |
| 821 | | | **Personal access tokens** | Owners | The workspace's rules for members' tokens, and approving them. `-/personal-access-tokens` | |
| 822 | | **Money** | [**Usage**](/guides/usage-and-billing/#the-usage-page) | Members | What the workspace used, by product, project and day. `-/usage` | |
| 823 | | | [**Billing and plans**](/guides/usage-and-billing/) | Members | The plan, the spend limit and budget alerts, prepaying and every charge. `-/billing` | |
| 824 | | **Compute** | [**Runners**](/guides/self-hosted-runners/) | Owners | The workspace's self-hosted machines, their groups and registration tokens. `-/runners` | |
| 825 | | **Code** | **Repositories** | Members | Every repository, and for owners **Recently deleted**, where a [deleted repository](/guides/managing-repositories/#restore-a-repository) can be restored, or purged, for 30 days. `-/repositories` | |
| 826 | | | **Actions** | Members | How workflows run in the workspace: what jobs' tokens may do, and for owners the [workflows the workspace manages](#workflows-the-workspace-manages) in its repositories. `-/actions` | |
| 827 | | | [**Secrets and variables**](/guides/secrets-and-variables/) | Members | What runs and deployments are given. Owners change them. `-/secrets` | |
| 828 | | | [**Webhooks**](/guides/webhooks/) | Members | Where the workspace's events are sent. Owners add and change them. `-/webhooks` | |
| 829 | | **Chat** | [**Chat settings**](/guides/chat/#workspace-chat-settings) | Members | Renaming and archiving channels, emoji, default channels. Owners change it. `-/settings/chat` | |
| 830 | | | **Emoji** | Members | The workspace's own emoji. `-/emoji` | |
| 831 | | **Security** | **Security settings** | Members | The workspace's security policies. `-/security/settings` | |
| 832 | | | [**Guardrails**](/guides/guardrails/) | Members | How long checks, the merge queue and merge checks may run. `-/guardrails` | |
| 833 | | | [**Rules**](/guides/rules/) | Members | Rulesets across projects. `-/rules` | |
| 834 | | | [**Audit log**](/guides/audit-log/) | Members | Every change, by whom, to what. `-/audit` | |
| 835 | | **Integrations** | [**Integrations**](/guides/integrations/) | Members | The tools connected for everyone. `-/integrations` | |
| 836 | |
| 837 | Each page's address is under `g1t.sh/<workspace>/`. The page's header |
| 838 | shows where you are: **General**, **Members / Invitations**, **Permissions**. |
| 839 | Every address that was there before this layout still works. To find |
| 840 | someone, and what they work on, use the |
| 841 | [People directory](/guides/people-and-teams/#the-directory). |
| 842 | |
| 843 | ### Pinned and recent projects |
| 844 | |
| 845 | However many projects a workspace has, Code's sidebar lists a few: |
| 846 | |
| 847 | - **Pinned**: the projects you pinned, in your order, up to eight a |
| 848 | workspace. Pin one with **Pin** on its page, or the pin on its row of the |
| 849 | Projects page or its card on the Overview. Drag a pinned project to move |
| 850 | it, or hold <kbd>Alt</kbd> and press the up or down arrow. |
| 851 | - **Recent**: the projects you opened last that you have not pinned, up to |
| 852 | five. |
| 853 | - **All projects**, with how many there are, opens the Projects page. |
| 854 | |
| 855 | Pins and recent projects are yours: nobody else sees them, and each |
| 856 | workspace has its own. ⌘K finds any project in the workspace, pinned or not. |
| 857 | From the API, use |
| 858 | [`GET /user/pinned_projects/{workspace}`](/reference/api/pinned-projects/list-pinned-projects/) |
| 859 | and the other [pinned projects](/reference/api/pinned-projects/list-pinned-projects/) |
| 860 | operations, or the `workspace` tool's `list_pinned_projects`, |
| 861 | `pin_project`, `unpin_project` and `reorder_pinned_projects` actions |
| 862 | over MCP. |
| 863 | |
| 864 | ### On your phone |
| 865 | |
| 866 | On a screen narrower than a tablet, g1t keeps the same places and moves |
| 867 | them within reach of your thumb: |
| 868 | |
| 869 | | | What it does | |
| 870 | | --- | --- | |
| 871 | | **The bar along the bottom** | **Home**, **Chat**, **Notifications** and **Code** (for members with Code access), each with what is unread, and **More**. It runs flat along the bottom edge, as the rail stands beside the page on a computer, and the page fills the screen above it. The app you are in is marked as on the rail. It steps aside while the keyboard is up and inside a conversation. | |
| 872 | | **More** | A panel above the bar with **Artifacts**, **People**, **Workspace**, and **You and help**: your status, profile and settings, [appearance](#appearance), the documentation, support, status, the keyboard's shortcuts and signing out. | |
| 873 | | **The sidebar button**, at the left of the page's header | Opens the sidebar of the app you are in from the left, most of the screen wide: the same lists and links as on a computer. Tap outside it, or open a page, and it closes. | |
| 874 | | **The tab you are already on** | Tap it again to open that app's sidebar too. | |
| 875 | | **The workspace's name** in the page's header | Switches workspace, or opens your profile or settings. | |
| 876 | |
| 877 | Inside a [project](/guides/projects/), its pages (**Overview**, **Code**, |
| 878 | **Work**, **Pull requests**, **Workflows**, **Deployments**, |
| 879 | **Insights** and, for the roles that see them, **Security** and |
| 880 | **Settings**) run in a row under its name that scrolls sideways, with the |
| 881 | page you are on kept in view, so work items and pull requests are one tap |
| 882 | away. Pages with more than one view, such as **Files**, **Commits** and |
| 883 | **Branches**, show those as a second row of tabs. |
| 884 | |
| 885 | Menus stay inside the screen, dialogs rise from the bottom and sit on top |
| 886 | of the keyboard while you type, and nothing scrolls the page sideways: a |
| 887 | wide file, diff or table scrolls within its own box. |
| 888 | |
| 889 | ### Signed out, and signing in |
| 890 | |
| 891 | Signing in, signing up, an invite link, the two-factor step, choosing a new |
| 892 | password and making your first workspace each stand on their own: the g1t |
| 893 | logo, the form, and links to the terms, privacy policy, docs, status and |
| 894 | support at the foot. Someone who is not signed in reads public pages, such |
| 895 | as Explore, a profile or a public project, under a plain header with |
| 896 | **Explore**, **Docs**, **Sign in** and **Sign up**; a project's pages run in |
| 897 | the row under its name. |
| 898 | |
| 899 | ## Mission control |
| 900 | |
| 901 | Mission control is Code's **Overview**, at `g1t.sh/<workspace>/-/overview`. |
| 902 | It shows where you are needed in the workspace's code and what landed. |
| 903 | Signed in, `g1t.sh` itself opens [Home](/guides/home/) in the workspace |
| 904 | you are in. |
| 905 | |
| 906 | **Review N that need you** jumps to the list, and **New work item** opens |
| 907 | a new [work item](/guides/work-items/) of the workspace, filed in the |
| 908 | project you pick. |
| 909 | |
| 910 | | Tab | What it lists | |
| 911 | | --- | --- | |
| 912 | | **Needs you** | Reviews asked of you, changes ready for you to merge, failed checks, failed production builds, repository invitations and a usage limit that is close or reached. | |
| 913 | | **Landed today** | Pull requests merged today in your time zone, and whether a person merged them. | |
| 914 | |
| 915 | Each row in **Needs you** carries the reason it needs you: |
| 916 | |
| 917 | | Reason | Means | |
| 918 | | --- | --- | |
| 919 | | `BLOCKING` | Nothing moves until a person acts: a failed production build, a merge g1t could not make, or the usage limit. | |
| 920 | | `ASKED FOR YOU` | A review or an invitation addressed to you by name. | |
| 921 | | `CHECKS FAILING` | A required check fails. | |
| 922 | | `NEEDS REVIEW` | The repository wants a person's approval. | |
| 923 | | `READY TO MERGE` | Checks passed and it was approved; the repository lands changes only when a person merges them. | |
| 924 | |
| 925 | From a row, **Review and respond** opens it, and where it can be done |
| 926 | without leaving the page you can approve the change, merge it or re-run |
| 927 | its failed jobs. **By impact** puts the most urgent first; **Newest** sorts |
| 928 | by time. |
| 929 | |
| 930 | ## Workspace access tokens |
| 931 | |
| 932 | A workspace has access tokens of its own, for CI, integrations and coding |
| 933 | agents that work for a team. There is no shared service account to create, pay |
| 934 | for or lose the password to. |
| 935 | |
| 936 | | | Personal token | Workspace token | |
| 937 | | --- | --- | --- | |
| 938 | | Belongs to | You | The workspace | |
| 939 | | Acts as | You | The workspace: its name is the author of what it does | |
| 940 | | Can reach | All your workspaces, one of them, or none ([where a token reaches](/guides/authentication/#where-a-token-reaches)) | That workspace only: all of its repositories, or the ones chosen | |
| 941 | | Can do | What its [permissions](/guides/authentication/#permissions) allow, never more than you can | What its permissions allow, with Write on the workspace's repositories (Admin with Repositories: admin); it cannot manage people, tokens or workspaces, and holds no account permissions | |
| 942 | | Expires | 7 days to 1 year, or never where the workspaces it reaches allow | 7 days to 1 year, or never | |
| 943 | | When its creator leaves | Stops working | Keeps working | |
| 944 | | Created by | You, in [Settings → Access tokens](https://g1t.sh/settings/tokens) | An owner, under the workspace's **Settings → Access tokens** | |
| 945 | |
| 946 | They are the same kind of token and are sent the same way; see |
| 947 | [access tokens](/guides/authentication/#access-tokens). With git, any |
| 948 | username works; the token is the password. `GET /user` answers with |
| 949 | `"kind": "workspace"` for one, and `"kind": "user"` for a personal token. |
| 950 | |
| 951 | Every member can see a workspace's tokens: the name, who created each, |
| 952 | its permissions and repositories, when it was last used and when it |
| 953 | expires. Only owners can create, change or delete them. An owner selects |
| 954 | **New token** and fills in the same form as a personal token: a name, an |
| 955 | expiration (No expiration shows a warning), its repositories (all, or the |
| 956 | ones chosen) and its permissions, starting on the CI preset. Each token |
| 957 | shows **Write** or **Admin**: give it **Repositories: admin** to let it |
| 958 | manage webhooks, secrets, deploy keys and who has access, and teams as an |
| 959 | owner would. Select a token to change its permissions or repositories, or |
| 960 | to delete it. |
| 961 | |
| 962 | Which of your members' own personal tokens reach the workspace is set under |
| 963 | **Settings → Personal access tokens**; see |
| 964 | [a workspace's rules for tokens](/guides/authentication/#a-workspaces-rules-for-tokens). |
| 965 | |
| 966 | ## Profiles |
| 967 | |
| 968 | Every person has a profile at `g1t.sh/u/<username>`, apart from the |
| 969 | workspaces at `g1t.sh/<workspace>`. Author names on work items and pull |
| 970 | requests link to it. |
| 971 | |
| 972 | **What it shows.** Your picture, name, username, pronouns, bio, location, |
| 973 | website and when you joined; then your work in three tabs: |
| 974 | |
| 975 | - **Overview:** your contribution calendar, then pull requests merged, |
| 976 | open pull requests and work items opened, and your most recent activity. |
| 977 | - **Pull requests** and **Work items:** everything you opened, and what g1t |
| 978 | opened for you, newest first, |
| 979 | with filters beside the list for state (open, closed, merged), type, |
| 980 | repository and sort order. Each tab has its own address, such as `g1t.sh/u/<username>/pulls`; |
| 981 | add `?state=merged` and the like to |
| 982 | link to a filtered list. |
| 983 | |
| 984 | **The contribution calendar.** The last year as a square a day, a column a |
| 985 | week, shaded more strongly the more you did that day, with the total |
| 986 | above it ("128 contributions in the last year"). A contribution is a |
| 987 | commit you pushed, a work item or pull request you opened (or g1t opened for |
| 988 | you), and a review you gave. Days are counted in UTC. Hover over a square, |
| 989 | or tap it, to see its day, its count and how many were commits ("5 |
| 990 | contributions on Oct 4, 2026, 3 of them commits"). On a narrow screen the |
| 991 | calendar scrolls sideways inside its card, starting at today. |
| 992 | |
| 993 | Commits count like this: |
| 994 | |
| 995 | - **Pushed to the default branch, or to `gh-pages`.** Commits on other |
| 996 | branches count once they reach the default branch, which is usually a |
| 997 | pull request, and the pull request is counted already. |
| 998 | - **Credited to whoever pushed,** on the day of the push, not to the |
| 999 | commits' authors. Pushes with a workspace's or a workflow job's token are |
| 1000 | not counted on anyone's calendar. |
| 1001 | - **The new commits along the branch's own line,** at most 50 a push. A |
| 1002 | merge commit counts once. The first push of a branch counts one, so |
| 1003 | importing a long history doesn't fill a single day. |
| 1004 | - **Only from the time this was added:** pushes before 9 October 2026 are |
| 1005 | not counted. |
| 1006 | |
| 1007 | **Edit it** in [Settings → Profile](https://g1t.sh/settings/profile). Every |
| 1008 | field is optional. The bio takes up to 160 characters and is also what a |
| 1009 | link to your profile says. The website must be an `https://` address; |
| 1010 | `example.com` is saved as `https://example.com`. Your email address is |
| 1011 | never shown. |
| 1012 | |
| 1013 | **Time zone.** Pick the time zone you are in, by city or region (such as |
| 1014 | `America/Denver`), and the [card over your name](#the-card-over-a-name) |
| 1015 | shows your local time, so people can tell whether it is a good moment to |
| 1016 | ask you something. If your browser's time zone differs from the one |
| 1017 | saved, the field offers **Use my browser's time zone**. Choose **Not |
| 1018 | shown** to clear it. |
| 1019 | |
| 1020 | **Who sees what.** A profile is public, but the work and workspaces on it |
| 1021 | are filtered for whoever is looking: |
| 1022 | |
| 1023 | | On the profile | Shown to a visitor when | |
| 1024 | | --- | --- | |
| 1025 | | A pull request, and its title | They can read its repository: it is public, or they are a member of its workspace | |
| 1026 | | A work item, and its title | They are a member of its workspace, or can read the repository it was filed in | |
| 1027 | | The counts, and the contribution calendar | Only what they could see is counted | |
| 1028 | | A workspace | They are a member of it too, or you made a public project in it, whose page shows that already | |
| 1029 | |
| 1030 | Someone signed out sees your public work and the workspaces where you made |
| 1031 | a public project; nothing else, and their calendar counts only work in |
| 1032 | public repositories. The link preview for a profile uses only public work. |
| 1033 | |
| 1034 | **How it is laid out.** Signed out, a profile, Explore and Search are |
| 1035 | shown with g1t's public header (search, Explore, Docs, signing in) and the page |
| 1036 | at full width, with no workspace sidebar. Signed in, the rail stays with |
| 1037 | **Explore** lit, and Explore's sidebar opens beside these pages, with the |
| 1038 | person you are looking at under **You are viewing** (see |
| 1039 | [The rail, the sidebar and the page](#the-rail-the-sidebar-and-the-page)). |
| 1040 | Your own profile is browsing too, with **Your profile** lit. |
| 1041 | |
| 1042 | ### The card over a name |
| 1043 | |
| 1044 | Hold the pointer over a person's name or picture anywhere on g1t, or move |
| 1045 | the keyboard focus to their name, and a card opens with their profile at a |
| 1046 | glance: |
| 1047 | |
| 1048 | | On the card | Shown when | |
| 1049 | | --- | --- | |
| 1050 | | Picture, name, username and pronouns | Always | |
| 1051 | | Bio and location | They filled them in | |
| 1052 | | Their local time, such as **3:42 PM local time** | They set a [time zone](#profiles) | |
| 1053 | | **Member of** | The same workspaces their profile shows you, at most three named | |
| 1054 | | **Committed to this repository in the past day**, **week** or **month** | You opened it inside a repository you can read, and their latest commit on its default branch is that recent | |
| 1055 | |
| 1056 | On a touch screen no card opens: a tap goes to the profile. `@g1t` has a |
| 1057 | card of its own, about putting g1t to work. `ghost`, which stands in for |
| 1058 | deleted accounts, has no card. |
| 1059 | |
| 1060 | ### Commits and your account |
| 1061 | |
| 1062 | A commit shows as yours, with your username, picture, profile link and |
| 1063 | card, when its author address is one of your |
| 1064 | [confirmed addresses](/guides/authentication/#email-addresses) or your |
| 1065 | noreply address. This holds everywhere a commit appears: the Files page, |
| 1066 | history, a commit, blame, branches, tags, comparisons and the |
| 1067 | Contributors list, which counts every address of yours as one person. |
| 1068 | |
| 1069 | To have commits made on your own machine show as yours without publishing |
| 1070 | your address, commit with your noreply address: |
| 1071 | |
| 1072 | 1. Open [Settings → Emails](https://g1t.sh/settings/emails) and copy your |
| 1073 | noreply address. It looks like |
| 1074 | `<8 characters of your account id>+<username>@users.noreply.g1t.sh`. |
| 1075 | 2. Set it for every repository, or leave out `--global` for one: |
| 1076 | |
| 1077 | ```sh |
| 1078 | git config --global user.email "6c1d0efg+sam@users.noreply.g1t.sh" |
| 1079 | ``` |
| 1080 | |
| 1081 | 3. Commit and push as usual. Commits you made before keep the address they |
| 1082 | were made with; add that address to your account and confirm it to have |
| 1083 | them show as yours. |
| 1084 | |
| 1085 | | A commit's address | Shown as | |
| 1086 | | --- | --- | |
| 1087 | | One of your confirmed addresses, or your noreply address | You | |
| 1088 | | An address added to an account but not confirmed | The name in the commit | |
| 1089 | | An address no account has | The name in the commit, with a plain picture, no link and no card | |
| 1090 | | A deleted account's noreply address, or any of its confirmed addresses during the 30 days it can be restored | `ghost` | |
| 1091 | | g1t's own (`g1t@users.noreply.g1t.sh`) | `g1t` | |
| 1092 | |
| 1093 | `Co-authored-by` trailers are matched the same way, and their pictures sit |
| 1094 | beside the author's. An address itself is never shown on g1t. |