| 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, member privileges, requiring two-factor authentication, and access tokens that belong to a workspace. |
| 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. After confirming your email |
| 14 | the first thing you do is create a workspace, and repositories go in it. |
| 15 | |
| 16 | 1. Open [g1t.sh/workspaces/new](https://g1t.sh/workspaces/new). |
| 17 | 2. Choose its name in URLs: lowercase letters, digits and single hyphens. |
| 18 | An owner can [change it later](#rename-a-workspace), and old addresses |
| 19 | redirect for 90 days. |
| 20 | 3. Optionally give it a display name. |
| 21 | |
| 22 | From the API, `POST /workspaces` with `slug` and `name`, or the |
| 23 | `workspace` tool's `create` action: |
| 24 | |
| 25 | ```sh |
| 26 | curl -X POST https://api.g1t.sh/workspaces \ |
| 27 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 28 | -H "Content-Type: application/json" \ |
| 29 | -d '{"slug": "acme", "name": "Acme"}' |
| 30 | ``` |
| 31 | |
| 32 | You can belong to up to ten workspaces. `GET /user`, or the `account` tool's `whoami` action, lists the |
| 33 | ones you belong to. |
| 34 | |
| 35 | A new workspace is free, and **each person can own one free workspace**. |
| 36 | While you own a free workspace, the page shows **You already own a free |
| 37 | workspace** in place of the form, with **Start the plan** on it; the API |
| 38 | answers `402` (`payment_required`). Start the plan on it, or delete it, |
| 39 | then create the new one. Several free workspaces from before are kept, but |
| 40 | each needs the plan (or deleting) before you can create another. See |
| 41 | [one free workspace per person](/guides/usage-and-billing/#one-free-workspace-per-person). |
| 42 | |
| 43 | Usernames and workspaces share one set of names, so a name means the same |
| 44 | thing wherever it appears. Your username is reserved for you: only you can |
| 45 | create a workspace with that name, and nobody can register a username that |
| 46 | is already a workspace. The names `g1t` and `g1t-agent` belong to |
| 47 | [g1t's agent](/guides/working-with-g1t/), and nobody can register them. |
| 48 | |
| 49 | ## Display name, slug and icon |
| 50 | |
| 51 | A workspace has two names: |
| 52 | |
| 53 | | | Example | Where it appears | Changes | |
| 54 | | --- | --- | --- | --- | |
| 55 | | **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 | |
| 56 | | **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) | |
| 57 | |
| 58 | Without a display name, the slug is shown. Where an address is shown, the |
| 59 | slug is in monospace beside the name. Owners change the display name and |
| 60 | description (up to 160 characters) on **Settings → General**, or with |
| 61 | [`PATCH /workspaces/{workspace}`](/reference/api/workspaces/update-workspace/) |
| 62 | (MCP: `workspace` `update`), which takes `name` and `description` and |
| 63 | changes only the fields given. It needs the `workspace:admin` scope, and |
| 64 | is recorded in the [audit log](/guides/audit-log/): |
| 65 | |
| 66 | ```sh |
| 67 | 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."}' |
| 68 | ``` |
| 69 | |
| 70 | Neither changes the slug; that is a [rename](#rename-a-workspace). |
| 71 | |
| 72 | A workspace also has an icon. Without |
| 73 | one, g1t draws its first letter in a colour of its own. To upload one, an |
| 74 | owner opens **Settings → General** and picks an image: |
| 75 | |
| 76 | - PNG, JPEG, WebP or GIF, at most 1 MB. Square images look best. |
| 77 | - An image is checked by its contents, not its name. SVG is refused, |
| 78 | because it can carry script. |
| 79 | - **Remove** goes back to the letter. |
| 80 | |
| 81 | The icon then shows wherever the workspace does, and on its link previews |
| 82 | (PNG and JPEG icons only). Each image is served from |
| 83 | `g1tusercontent.com/avatars/<sha256>`, an address named after its contents, so an icon |
| 84 | that changes gets a new address and nothing shows the old one. |
| 85 | |
| 86 | You can upload a picture of yourself the same way, under |
| 87 | [Settings → Profile](https://g1t.sh/settings/profile). |
| 88 | |
| 89 | ## Rename a workspace |
| 90 | |
| 91 | Renaming changes the slug, the first part of every address under the |
| 92 | workspace. The display name is separate; change it on its own under |
| 93 | **Settings → General → Workspace details**. Only owners can rename a |
| 94 | workspace. |
| 95 | |
| 96 | 1. Open the workspace's **Settings → General** and go to **Address**. |
| 97 | 2. Type the new slug. The field shows the new address, `g1t.sh/<new>`, and |
| 98 | whether the name is available. |
| 99 | 3. Choose **Change address**, read what changes, type the new slug to |
| 100 | confirm, and choose **Change address** again. |
| 101 | |
| 102 | You land on the workspace's settings at its new address. Repositories, |
| 103 | issues and the rest move with it within a few seconds. |
| 104 | |
| 105 | ### What changes |
| 106 | |
| 107 | | | Before | After | |
| 108 | | --- | --- | --- | |
| 109 | | Pages | `g1t.sh/old/<repo>` | `g1t.sh/new/<repo>` | |
| 110 | | Git remotes | `https://g1t.sh/old/<repo>.git` | `https://g1t.sh/new/<repo>.git` | |
| 111 | | API paths | `https://api.g1t.sh/repos/old/<repo>` | `https://api.g1t.sh/repos/new/<repo>` | |
| 112 | | MCP tool arguments | `"owner": "old"` | `"owner": "new"` | |
| 113 | | Production apps | `https://<project>-old.g1t.page` | `https://<project>-new.g1t.page` | |
| 114 | | Previews | `https://<project>-git-<branch>-old.g1t.page` | `https://<project>-git-<branch>-new.g1t.page` | |
| 115 | |
| 116 | These stay the same: the display name, description and icon, members and |
| 117 | roles, access tokens, secrets and variables, integrations, webhooks, |
| 118 | issues and pull requests, and billing, plans and credit. |
| 119 | |
| 120 | ### What redirects, and for how long |
| 121 | |
| 122 | For 90 days after a rename, the old name keeps working: |
| 123 | |
| 124 | | | Behaviour | |
| 125 | | --- | --- | |
| 126 | | Web pages | Answer with a permanent redirect (301) to the same page under the new name, query string included. | |
| 127 | | `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. | |
| 128 | | API and MCP | A call that names the old slug runs under the new one. | |
| 129 | | `g1t.page` apps | Production and preview addresses under the old name redirect to the new ones. | |
| 130 | |
| 131 | Update your remotes now rather than relying on the redirect: |
| 132 | |
| 133 | ```sh |
| 134 | git remote set-url origin https://g1t.sh/<new>/<repo>.git |
| 135 | ``` |
| 136 | |
| 137 | Update anything else that has the old name written into it, too: links in |
| 138 | READMEs and docs, CI configuration, API clients and MCP clients. |
| 139 | |
| 140 | ### Limits |
| 141 | |
| 142 | - A workspace can be renamed once every 24 hours. |
| 143 | - For 90 days the old name is held for the workspace. Nobody else can take |
| 144 | it, and you can rename back to it. |
| 145 | - After 90 days the redirects stop, and anyone can create a workspace or |
| 146 | register a username with the old name. Links and remotes that still use |
| 147 | it then reach whatever has the name, or nothing. |
| 148 | - The new name follows the same rules as a new workspace: lowercase letters, |
| 149 | digits and single hyphens, up to 39 characters, not a reserved word, and |
| 150 | not another workspace's slug or someone else's username. |
| 151 | |
| 152 | ## Data residency |
| 153 | |
| 154 | Data residency says where the git data of the workspace's new repositories |
| 155 | is stored. The section appears in **Settings** once g1t can store |
| 156 | repositories in the EU. Until then it is not shown, and every repository is |
| 157 | stored wherever g1t stores repositories. |
| 158 | |
| 159 | | Setting | What it does | |
| 160 | | --- | --- | |
| 161 | | Anywhere | New repositories are stored wherever g1t stores repositories. The default. | |
| 162 | | 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. | |
| 163 | |
| 164 | To change it: |
| 165 | |
| 166 | 1. Open the workspace, then **Settings**. Only owners see the page. |
| 167 | 2. Under **Data residency**, choose **Anywhere** or **EU only**. |
| 168 | 3. Select **Save**. |
| 169 | |
| 170 | The setting applies to repositories made after you save it, however they |
| 171 | are made: from the site, with the API, by pushing to a new address, or by |
| 172 | importing. Repositories the workspace already has stay where they are. To |
| 173 | move them, contact support; a move keeps each repository's address, history |
| 174 | and settings, and pushes to it wait a few minutes while it happens. |
| 175 | |
| 176 | Data residency covers the git data: commits, branches, tags and files, |
| 177 | including pull requests' working copies, which are stored with their |
| 178 | repository. Issues, pull requests, comments and settings are not affected. |
| 179 | A repository [transferred](/guides/transferring-repositories/) to another |
| 180 | workspace stays where it is stored. |
| 181 | |
| 182 | Changing the setting is recorded in the |
| 183 | [audit log](/guides/audit-log/) as `workspace.residency_changed`. |
| 184 | |
| 185 | ## Delete a workspace |
| 186 | |
| 187 | Deleting a workspace takes everything in it with it, in one step: its |
| 188 | repositories, projects, apps, members' access and tokens. Only an owner can, |
| 189 | signed in as a person, typing the workspace's slug to confirm. |
| 190 | |
| 191 | It is not gone at once. For **30 days** g1t keeps all of it, so that a |
| 192 | deletion you did not mean, or did not make, can be undone: an owner writes |
| 193 | to support@g1t.sh, and support restores the workspace as it was. After 30 |
| 194 | days it is purged for good. |
| 195 | |
| 196 | 1. Open the workspace's **Settings → General** and go to **Danger zone**. |
| 197 | It lists what will go with the workspace: its repositories, projects, |
| 198 | live apps and members. |
| 199 | 2. Choose **Delete workspace**, read what happens, type the workspace's |
| 200 | slug to confirm, and choose **Delete workspace** again. You are taken |
| 201 | back to your own home. |
| 202 | |
| 203 | The one thing that can stand in the way is billing: see |
| 204 | [what billing needs](#what-billing-needs). Repositories you want to keep in |
| 205 | another workspace, [transfer](/guides/transferring-repositories/) first; |
| 206 | their old addresses keep redirecting after the workspace is gone. |
| 207 | |
| 208 | From the API, call |
| 209 | [`DELETE /workspaces/{workspace}`](/reference/api/workspaces/delete-workspace/) |
| 210 | with the slug in `confirm`; over MCP, the `workspace` tool's `delete` |
| 211 | action. |
| 212 | |
| 213 | Some workspaces can never be deleted, by anyone, such as Flagon's, which |
| 214 | runs g1t. Their Danger zone says so instead of offering the button. |
| 215 | |
| 216 | ### What billing needs |
| 217 | |
| 218 | | | | |
| 219 | | --- | --- | |
| 220 | | Money owed | Charged to the workspace's card at once, with no minimum charge. With no card, add one or pay from **Billing** first. | |
| 221 | | An unpaid invoice | Pay it from **Billing** first. | |
| 222 | | Prepaid credit | It would be lost: spend it, or write to support@g1t.sh about a refund, first. | |
| 223 | | 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. | |
| 224 | | The g1t plan | Ends at Stripe at once, not at the end of the period. | |
| 225 | | An enterprise account | A workspace billed through one is moved off it by g1t first: write to support@g1t.sh. | |
| 226 | |
| 227 | A comped workspace owes nothing; only its plan is ended. |
| 228 | |
| 229 | ### What happens |
| 230 | |
| 231 | At once, when an owner deletes it: |
| 232 | |
| 233 | | | | |
| 234 | | --- | --- | |
| 235 | | 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. | |
| 236 | | Access tokens | The workspace's own tokens stop working. Personal tokens are not affected. | |
| 237 | | Repositories | Deleted with it: git refuses them, and their pages answer 404. Agents and workflow runs stop. Ones deleted on their own earlier stay deleted. | |
| 238 | | Projects and apps | Hidden. Its apps are taken offline and nothing builds. Custom domains are kept for a restore. | |
| 239 | | Its pages | Answer 404, and it drops out of search. | |
| 240 | | Billing | What it owes is charged, and its plan ends, as [billing needs](#what-billing-needs). Nothing more is charged. | |
| 241 | | The audit log | Records the deletion. | |
| 242 | |
| 243 | Within 30 days, support can restore it: its members, tokens, repositories, |
| 244 | projects and apps come back as they were, and its apps go back up as its |
| 245 | limit allows. Its plan does not come back by itself: an owner starts it |
| 246 | again from **Billing**. A repository deleted on its own before the |
| 247 | workspace was stays in **Recently deleted**. |
| 248 | |
| 249 | After 30 days it is purged: |
| 250 | |
| 251 | | | | |
| 252 | | --- | --- | |
| 253 | | Repositories | Purged, their git data with them, including any that were in Recently deleted. | |
| 254 | | Projects, apps and custom domains | Removed. | |
| 255 | | Webhooks, integrations, secrets and variables | The workspace's own are removed. | |
| 256 | | Memory and guardrails | The workspace's own are removed. | |
| 257 | | Statements, invoices and the ledger | Kept, for accounting. | |
| 258 | | 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. | |
| 259 | | Old addresses | Redirects for repositories transferred out keep working. The workspace's own pages answer 404. | |
| 260 | |
| 261 | ### The name afterwards |
| 262 | |
| 263 | A deleted workspace's slug is never given to another workspace or used as |
| 264 | someone else's username. While it can still be restored, the slug is held |
| 265 | for it. Links and git remotes that still use it keep |
| 266 | meaning what they meant: a transferred repository's old address keeps |
| 267 | redirecting to it, and nobody can take the name in the meantime. |
| 268 | |
| 269 | The one exception: when the slug is your own username, you may create a |
| 270 | workspace with that name again once the old one is purged. It starts empty, on standard billing terms, |
| 271 | and a repository made in it at an old address ends that address's redirect. |
| 272 | |
| 273 | ## Members and roles |
| 274 | |
| 275 | <a id="members-and-owners"></a> |
| 276 | |
| 277 | | Role | Can | |
| 278 | | --- | --- | |
| 279 | | 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, merge pull requests, plan work and put g1t to work. Admin on the repositories they create. | |
| 280 | | 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/). | |
| 281 | |
| 282 | A workspace can have any number of owners, and always has at least one. |
| 283 | |
| 284 | ### Roles that add to a member |
| 285 | |
| 286 | An owner can give a member one or both of these roles. Each adds to what |
| 287 | the member already has; an owner has both already. |
| 288 | |
| 289 | | Role | Adds | |
| 290 | | --- | --- | |
| 291 | | **Billing manager** | Manages the workspace's billing as an owner does: the plan, budget and spend limit, AI credit and auto-reload, the card, billing details and invoices. Gives nothing on repositories. | |
| 292 | | **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. | |
| 293 | |
| 294 | Neither passes to an agent working for the person. |
| 295 | |
| 296 | ### Change someone's role |
| 297 | |
| 298 | On **People**, an owner opens the **⋯** menu beside a member: |
| 299 | |
| 300 | 1. **Make owner** or **Make member** changes their role. |
| 301 | 2. **Billing manager** and **Security manager** turn each role on or off. |
| 302 | 3. **Transfer ownership…** hands the workspace to that member: they become |
| 303 | an owner and you a member, in one step. To add an owner without stepping |
| 304 | down, choose **Make owner** instead. |
| 305 | 4. **Remove from {workspace}…** takes them out. Their roles on its |
| 306 | repositories and their place in its teams go too. |
| 307 | |
| 308 | Owners see a shield beside each member: green when two-factor |
| 309 | authentication is on, amber when it is off. |
| 310 | |
| 311 | The last owner cannot be made a member, removed, or leave: make someone |
| 312 | else an owner first, or [delete the workspace](#delete-a-workspace). |
| 313 | |
| 314 | ### Leave a workspace |
| 315 | |
| 316 | Anyone can leave a workspace they belong to: at the bottom of **People**, |
| 317 | choose **Leave {workspace}** and confirm. Your roles on its repositories |
| 318 | and your place in its teams go with you at once. The only owner cannot |
| 319 | leave. |
| 320 | |
| 321 | ### Add people |
| 322 | |
| 323 | Whoever creates a workspace is its owner. An owner adds people on the |
| 324 | workspace's **People**, `g1t.sh/<workspace>/-/people` (in the sidebar): |
| 325 | |
| 326 | - **By username**: someone already on g1t joins at once, as a member. |
| 327 | - **By email address**: g1t emails an invite that only that address can |
| 328 | use. Without a g1t account, accepting it makes the account and joins the |
| 329 | workspace in one step, and uses one of the workspace's granted invites, or |
| 330 | else one of yours (see [invites](/guides/authentication/#invites)). With |
| 331 | an account, it costs nothing, and they join when they accept. The page |
| 332 | never says which it was. |
| 333 | |
| 334 | The email names you and the workspace and links to the invite's page. |
| 335 | Someone new signs up right there, with the invited address filled in, and |
| 336 | joins at once when they opened the page from that email (it proves the |
| 337 | address is theirs), or otherwise once they confirm it with the code g1t |
| 338 | emails them; someone with an account signs in. Either way they land in the workspace as a member, with |
| 339 | a one-time welcome. Until a new account confirms its address, its invite |
| 340 | shows as **confirming their email** under the members, and you can still |
| 341 | revoke it. See |
| 342 | [using an invite](/guides/authentication/#using-an-invite). |
| 343 | |
| 344 | Pending invites are listed under the members, with a link to copy and |
| 345 | **Revoke**. Through the API, use |
| 346 | [`POST /workspaces/{workspace}/invitations`](/reference/api/invites/invite-member/) |
| 347 | (the `workspace` tool's `invite_member` action over MCP). |
| 348 | |
| 349 | To give someone a role on one repository without making them a member, |
| 350 | add them as an [outside collaborator](/guides/access-and-roles/#outside-collaborators). |
| 351 | |
| 352 | **A free workspace cannot add people.** Until it starts the g1t plan, it |
| 353 | cannot add members, send invites, or invite outside collaborators, and an |
| 354 | invite sent before waits until the plan is on. Its members stay. People |
| 355 | shows **Start the plan to invite people** with the button in place of the |
| 356 | form, and the API and MCP answer `402` (`payment_required`). See |
| 357 | [who a free workspace can add](/guides/usage-and-billing/#who-a-free-workspace-can-add). |
| 358 | |
| 359 | ### Members through the API |
| 360 | |
| 361 | | Route | MCP tool and action | What it does | Who | |
| 362 | | --- | --- | --- | --- | |
| 363 | | `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 | |
| 364 | | `PATCH /workspaces/{workspace}/members/{username}` | `workspace` `update_member` | Change `role` and `org_roles` (a list that replaces theirs). | Owners | |
| 365 | | `DELETE /workspaces/{workspace}/members/{username}` | `workspace` `remove_member` | Remove someone. Your own username is leaving. | Owners | |
| 366 | | `POST /workspaces/{workspace}/transfer_ownership` | `workspace` `transfer_ownership` | Hand it to `username`: they become an owner, you a member. | Owners | |
| 367 | | `DELETE /user/memberships/{workspace}` | `workspace` `leave` | Leave it. | You | |
| 368 | |
| 369 | Each is for people, signed in or with a personal access token; never an |
| 370 | agent. A change that would leave no owner answers `409`. |
| 371 | |
| 372 | ```sh |
| 373 | curl -X PATCH https://api.g1t.sh/workspaces/acme/members/grace \ |
| 374 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 375 | -d '{"org_roles": ["security_manager"]}' |
| 376 | ``` |
| 377 | |
| 378 | ## Member privileges |
| 379 | |
| 380 | What members can do beyond their role on each repository. Owners set them |
| 381 | in the workspace's **Settings → Member privileges**, |
| 382 | `g1t.sh/<workspace>/-/settings#member-privileges`, and can always do all of |
| 383 | it themselves. |
| 384 | |
| 385 | | Setting | Default | When on | |
| 386 | | --- | --- | --- | |
| 387 | | **Members can create public repositories** (`members_can_create_public_repositories`) | On | Any member can create a public repository. | |
| 388 | | **Members can create private repositories** (`members_can_create_private_repositories`) | On | Any member can create a private repository. | |
| 389 | | **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. | |
| 390 | | **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. | |
| 391 | | **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. | |
| 392 | |
| 393 | When one is off, only owners can do it; the refusal says so. Someone who is |
| 394 | not a member, an outside collaborator with Admin, never gets these. |
| 395 | Forking private repositories is not a setting: g1t has no personal forks |
| 396 | to allow or refuse. |
| 397 | |
| 398 | Through the API, `GET /workspaces/{workspace}` returns each by its name, |
| 399 | and [`PATCH /workspaces/{workspace}`](/reference/api/workspaces/update-workspace/) |
| 400 | sets any of them (`workspace` `update` over MCP). Each change is in the |
| 401 | [audit log](/guides/audit-log/) as `workspace.member_privileges_changed`. |
| 402 | |
| 403 | ## Require two-factor authentication |
| 404 | |
| 405 | An owner can require everyone with access to the workspace, its members |
| 406 | and its outside collaborators, to have |
| 407 | [two-factor authentication](/guides/authentication/#two-factor-authentication) |
| 408 | on. |
| 409 | |
| 410 | 1. Turn it on for your own account first. |
| 411 | 2. Open **Settings**, `g1t.sh/<workspace>/-/settings#two-factor`. Under |
| 412 | **Authentication security**, it says how many members do not have it on, |
| 413 | and who. |
| 414 | 3. Turn on **Require two-factor authentication** and choose **Save**. |
| 415 | |
| 416 | From then on, someone without it keeps their place but cannot use the |
| 417 | workspace: its private repositories, pages and API answer as if they were |
| 418 | not a member, and every page shows them a notice with a link to turn it |
| 419 | on. Turning it on gives everything back at once. Nobody can join or accept |
| 420 | an invitation to the workspace without it. |
| 421 | |
| 422 | Through the API, `two_factor_requirement_enabled` on |
| 423 | `PATCH /workspaces/{workspace}`. Recorded as `workspace.two_factor_required` |
| 424 | and `workspace.two_factor_not_required`. |
| 425 | |
| 426 | ## The workspace's page |
| 427 | |
| 428 | A workspace's own page, `g1t.sh/<workspace>`, has its icon, name, address |
| 429 | and description at the top, then its overview: your |
| 430 | [pinned projects](#pinned-and-recent-projects), then the most active ones, |
| 431 | the pull requests in progress across them, and **All projects**. Members |
| 432 | also see a **Usage** card with this month's spend, and who belongs. |
| 433 | |
| 434 | The workspace's other pages each have a heading of their own and a row in |
| 435 | [the sidebar](#the-sidebar), lit while you are on them. The trail in the |
| 436 | top bar, such as *acme / Projects*, leads back to the workspace's page. |
| 437 | |
| 438 | | Page | Address | Who | | |
| 439 | | --- | --- | --- | --- | |
| 440 | | **Overview** | `g1t.sh/<workspace>` | Everyone | The page above. | |
| 441 | | **Projects** | `/-/projects` | Everyone | Every project you can see. See [the Projects page](#the-projects-page). | |
| 442 | | [**Packages**](/guides/packages/) | `/-/packages` | Everyone | What the workspace publishes. A visitor opens it from **Packages** on the workspace's page. | |
| 443 | | [**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>`. | |
| 444 | | **People** | `/-/people` | Members | Who belongs. Owners add and remove people here. | |
| 445 | | **Insights** | `/-/insights` | Members | Coming soon: how the whole workspace delivers. | |
| 446 | | **Settings** | `/-/settings` | Owners | How the workspace is set up and connected (below). | |
| 447 | |
| 448 | Each person sees the projects they can read: a member whose base permission |
| 449 | is None, an [outside collaborator](/guides/access-and-roles/#outside-collaborators) |
| 450 | or a visitor sees the public ones and those shared with them, without the |
| 451 | workspace's people, deployments or settings. |
| 452 | |
| 453 | Older addresses still work: `/-/members` opens People, and |
| 454 | `g1t.sh/<workspace>?tab=projects` (or `repositories`, `packages`, |
| 455 | `teams`, `people`, `insights` or `settings`) opens that page. |
| 456 | |
| 457 | ### The Projects page |
| 458 | |
| 459 | The Projects page, `g1t.sh/<workspace>/-/projects`, is made for workspaces with hundreds of projects: |
| 460 | |
| 461 | - **Find a project** matches every word you type in a project's name, its |
| 462 | address or its description. Press <kbd>/</kbd> anywhere on the page to |
| 463 | start typing. |
| 464 | - **Filters**: public or private; [what it is](/guides/projects/#what-a-project-is) |
| 465 | (apps, libraries, and tools, docs or other when the workspace has any); the language its |
| 466 | manifests say it is written in; only projects with |
| 467 | [Deployments](/guides/deployments/) on; and archived projects, which are |
| 468 | left out unless you ask for them. Each choice shows how many projects it |
| 469 | holds. |
| 470 | - **Sort** by recently updated (its settings or its last push, whichever is |
| 471 | later), recently pushed, most active, or name. Most active counts each |
| 472 | push, issue or pull request opened or closed, review, comment and |
| 473 | deployment, and what happened a week ago counts half as much. |
| 474 | - **List** or **grid**, 30 projects to a page. |
| 475 | - The arrow keys (or <kbd>j</kbd> and <kbd>k</kbd>) move between projects, |
| 476 | and <kbd>Enter</kbd> opens one. |
| 477 | |
| 478 | Everything you choose is in the address, so a filtered list can be |
| 479 | bookmarked or shared. |
| 480 | |
| 481 | ## The sidebar |
| 482 | |
| 483 | The sidebar is always about one workspace: the one the switcher at its top |
| 484 | names. On a workspace's pages, and on a project in one of your workspaces, |
| 485 | that is the workspace the page belongs to; on a project somewhere you are |
| 486 | not a member, it stays the one you chose last. Choose the workspace's name |
| 487 | to open its page, or the arrows beside it to switch, or for **Workspace |
| 488 | overview** and **All projects**. |
| 489 | [Explore](https://g1t.sh/explore), public projects from all of g1t, is in |
| 490 | the top bar, beside **Docs**. |
| 491 | |
| 492 | It has two parts, a rule apart. Above the rule is what is yours in every |
| 493 | workspace: **Mission control**, your **Inbox** with how many items are |
| 494 | unread, and the repositories **Shared with you** in workspaces you do not |
| 495 | belong to. Below it, under the workspace's name, is the workspace: |
| 496 | |
| 497 | 1. **Overview**, the [workspace's page](#the-workspaces-page). |
| 498 | 2. Its [projects](#pinned-and-recent-projects), ending with **All projects**. |
| 499 | 3. The places work happens across them: **Agent fleet**, **Context**, |
| 500 | **Memory**, **Security** and [**Packages**](/guides/packages/), with |
| 501 | **Insights**, **Boards** and **Roadmap** soon. |
| 502 | 4. **People**, [**Teams**](/guides/teams/), **Usage**, what g1t's runs have |
| 503 | cost (see [usage and billing](/guides/usage-and-billing/)), **Support** |
| 504 | and **Settings**. |
| 505 | |
| 506 | One row is lit wherever you are: **Teams** on a team's pages, **Packages** |
| 507 | on a package's, and **Settings** on every page it opens. An item with an arrow opens a list of its own in the sidebar: |
| 508 | **Settings** slides over to how the workspace is set up and connected, and |
| 509 | the row at the top, **‹ Settings**, slides back: |
| 510 | |
| 511 | | Settings | Who | | |
| 512 | | --- | --- | --- | |
| 513 | | **General** | Owners | The icon, the display name, a one-line description, the address (the slug), [who can create teams](/guides/teams/#who-can-create-teams), and [data residency](#data-residency). | |
| 514 | | **Repositories** | Members | The workspace's repositories. Owners also see **Recently deleted**, where a [deleted repository](/guides/managing-repositories/#restore-a-repository) can be restored, or purged, for 30 days. | |
| 515 | | **Access tokens** | Members | The workspace's own tokens. Owners create and delete them. | |
| 516 | | **Guardrails** | Members | What agents may do and spend across the workspace. Owners change them. | |
| 517 | | [**Secrets and variables**](/guides/secrets-and-variables/) | Members | What runs and deployments are given. Owners change them. | |
| 518 | | **Runners** | Owners | The workspace's self-hosted machines, their groups and registration tokens. | |
| 519 | | [**Integrations**](/guides/integrations/) | Members | Model providers and connected services. Owners connect and remove them. | |
| 520 | | [**Webhooks**](/guides/webhooks/) | Members | Where the workspace's events are sent. Owners add and change them. | |
| 521 | | **Billing and plans** | Members | [The g1t plan](/guides/usage-and-billing/#the-g1t-plan), [limits](/guides/usage-and-billing/#limits) and the statement. Owners start the plan, check a card, prepay and set limits. | |
| 522 | | **Audit log** | Members | [Every action agents, people and tokens took](/guides/audit-log/). | |
| 523 | |
| 524 | **People** is in the main list, for every member to see; owners add and |
| 525 | remove people there, set the |
| 526 | [base permission](/guides/access-and-roles/#the-base-permission), and see |
| 527 | the **Outside collaborators** tab. Each member's row also shows the |
| 528 | [teams](/guides/teams/) they are in that you can see. |
| 529 | |
| 530 | Opening a [project](/guides/projects/) slides the sidebar over to the |
| 531 | project's own list, with **‹ All projects** at the top to go back. Its |
| 532 | **Settings** opens one level further: **General**, **Deployments**, |
| 533 | **Domains**, **Agents**, **Guardrails**, **Repository**, **Access**, |
| 534 | **Branches and merging**, **Secrets and variables** and **Webhooks**, each |
| 535 | for the roles that can use it. A link straight to any of these pages opens |
| 536 | the sidebar already there. |
| 537 | |
| 538 | ### Pinned and recent projects |
| 539 | |
| 540 | However many projects a workspace has, its sidebar lists a few: |
| 541 | |
| 542 | - **Pinned**: the projects you pinned, in your order, up to eight a |
| 543 | workspace. Pin one with **Pin** on its page, or the pin on its row of the |
| 544 | Projects page or its card on the Overview. Drag a pinned project to move |
| 545 | it, or hold <kbd>Alt</kbd> and press the up or down arrow. |
| 546 | - **Recent**: the projects you opened last that you have not pinned, up to |
| 547 | five. |
| 548 | - **All projects**, with how many there are, opens the Projects page. |
| 549 | |
| 550 | Pins and recent projects are yours: nobody else sees them, and each |
| 551 | workspace has its own. ⌘K finds any project in the workspace, pinned or not. |
| 552 | From the API, use |
| 553 | [`GET /user/pinned_projects/{workspace}`](/reference/api/pinned-projects/list-pinned-projects/) |
| 554 | and the other [pinned projects](/reference/api/pinned-projects/list-pinned-projects/) |
| 555 | operations, or the `workspace` tool's `list_pinned_projects`, |
| 556 | `pin_project`, `unpin_project` and `reorder_pinned_projects` actions |
| 557 | over MCP. |
| 558 | |
| 559 | ## Mission control |
| 560 | |
| 561 | Mission control, `g1t.sh` when you are signed in, is your home page. It |
| 562 | shows where you are needed in the workspace you have chosen in the |
| 563 | sidebar, what its agents are doing, and what landed without you. |
| 564 | |
| 565 | Under the greeting, one line sums up the week, such as *Agents landed 37 |
| 566 | of their 39 changes this week without you, and people landed 8 changes of |
| 567 | their own*. An agent's change landed without you when g1t merged it, by |
| 568 | auto-merge or from the [merge queue](/guides/merge-queue/), with no person |
| 569 | pressing merge. People's changes are their merged pull requests and the |
| 570 | commits they pushed straight to the default branch. A push is a person's |
| 571 | by the account that signed in to make it, not by the name on its commits: |
| 572 | pushes by g1t or a workflow job's token, and commits g1t wrote, are not |
| 573 | counted as people's. **Review N that need you** jumps to the |
| 574 | list, and **New issue** opens a new issue in the project you pick. |
| 575 | |
| 576 | | Across the top | What it counts | |
| 577 | | --- | --- | |
| 578 | | **Projects** | The workspace's projects, and how many were added this month. | |
| 579 | | **Agents** | Agent runs going now, and the hours agents worked in the last 7 days. | |
| 580 | | **Changes this week** | Pull requests merged in the last 7 days, and commits people pushed straight to the default branch, with the change from the 7 days before. The change is left out when g1t cannot read far enough back to count it. | |
| 581 | | **Landed without you** | The share of agents' changes that g1t merged with no person pressing merge. People's own changes are not counted in it. | |
| 582 | | **Need you** | What is waiting on you, and how many of those block work. | |
| 583 | |
| 584 | The list has three tabs. Each row opens to say more; the first is open. |
| 585 | |
| 586 | | Tab | What it lists | |
| 587 | | --- | --- | |
| 588 | | **Needs you** | Pull requests g1t stopped seeing through, reviews asked of you, changes ready for you to merge, failed checks, quiet agents, failed production builds, repository invitations and a usage limit that is close or reached. | |
| 589 | | **Waiting on agents** | Pull requests in an agent's hands (making the change, checking, reviewing, revising, catching up or in the merge queue), and runs going now. | |
| 590 | | **Landed today** | Pull requests merged today in your time zone, and whether a person merged them. | |
| 591 | |
| 592 | Each row in **Needs you** carries the reason it needs you: |
| 593 | |
| 594 | | Reason | Means | |
| 595 | | --- | --- | |
| 596 | | `BLOCKING` | Nothing moves until a person acts: a failed production build, a merge g1t could not make, or the usage limit. | |
| 597 | | `ASKED FOR YOU` | A review or an invitation addressed to you by name. | |
| 598 | | `CHECKS FAILING` | A required check still fails after the agent revised. | |
| 599 | | `OUTSIDE GUARDRAILS` | A run reached a cost or time cap set in [Guardrails](/guides/guardrails/). | |
| 600 | | `NEEDS REVIEW` | The repository wants a person's approval, or the review still asks for changes after the agent revised. | |
| 601 | | `STALLED` | An agent stopped, or has reported nothing for 10 minutes. | |
| 602 | | `READY TO MERGE` | Checks passed and it was approved; the repository lands changes only when a person merges them. | |
| 603 | |
| 604 | Opened, a row shows **The ask** (what g1t stopped with, and who the work |
| 605 | was started for), **What the agent already knows** (its checks, the files |
| 606 | and lines it changes, the test files it touches, how often the agent was |
| 607 | sent back, and what its runs cost) and **Why this needs you**. From |
| 608 | there, **Review and respond** opens it, and where it can be done without |
| 609 | leaving the page you can approve the change, merge it or re-run its failed |
| 610 | jobs. **By impact** puts the most urgent first; **Newest** sorts by time. |
| 611 | |
| 612 | On the right, **This week** charts the changes landed each day, split |
| 613 | by who did the work: agents on their own, agents with a person merging, |
| 614 | and people (their pull requests and direct pushes, merges left out), with what |
| 615 | agents and sandboxes cost over the same days. **Activity** lists what |
| 616 | moved across the workspace, agents marked apart from people. The page |
| 617 | refreshes itself while agents are at work. |
| 618 | |
| 619 | ## Workspace access tokens |
| 620 | |
| 621 | A workspace has access tokens of its own, for CI, integrations and agents |
| 622 | that work for a team. There is no shared service account to create, pay |
| 623 | for or lose the password to. |
| 624 | |
| 625 | | | Personal token | Workspace token | |
| 626 | | --- | --- | --- | |
| 627 | | Belongs to | You | The workspace | |
| 628 | | Acts as | You | The workspace: its name is the author of what it does | |
| 629 | | Can reach | A classic token, every workspace you belong to; a fine-grained one, the one it names | That workspace only | |
| 630 | | Can do | What its [scopes](/guides/authentication/#scopes) or permissions allow, never more than you can | What its scopes allow, with Write on the workspace's repositories (Admin only when an owner gives it that); it cannot manage people, tokens or workspaces | |
| 631 | | Expires | A classic token: 7, 30 or 90 days (the default), 1 year, or never. A fine-grained one: within a year | 7, 30 or 90 days, 1 year, or never | |
| 632 | | When its creator leaves | Stops working | Keeps working | |
| 633 | | Created by | You, in [Settings → Access tokens](https://g1t.sh/settings/tokens) | An owner, under the workspace's **Settings → Access tokens** | |
| 634 | |
| 635 | They are the same kind of token and are sent the same way; see |
| 636 | [access tokens](/guides/authentication/#access-tokens). With git, any |
| 637 | username works; the token is the password. `GET /user` answers with |
| 638 | `"kind": "workspace"` for one, and `"kind": "user"` for a personal token. |
| 639 | |
| 640 | Every member can see a workspace's tokens: the name, who created each, |
| 641 | when it was last used and when it expires. Only owners can create or |
| 642 | delete them. An owner creates one with a name, an expiry (No expiry shows |
| 643 | a warning) and the same scope checklist as a classic personal token, |
| 644 | starting on the CI preset. Each token shows **Write** or **Admin**: tick |
| 645 | **Admin on the workspace's repositories** when making it to let it manage |
| 646 | webhooks, secrets, deploy keys and who has access, and teams as an owner |
| 647 | would. A token made before this choice existed has Write. |
| 648 | |
| 649 | Which of your members' own personal tokens reach the workspace is set under |
| 650 | **Settings → Personal access tokens**; see |
| 651 | [a workspace's rules for tokens](/guides/authentication/#a-workspaces-rules-for-tokens). |
| 652 | |
| 653 | ## Profiles |
| 654 | |
| 655 | Every person has a profile at `g1t.sh/u/<username>`, apart from the |
| 656 | workspaces at `g1t.sh/<workspace>`. Author names on issues and pull |
| 657 | requests link to it. |
| 658 | |
| 659 | **What it shows.** Your picture, name, username, pronouns, bio, location, |
| 660 | website and when you joined; then your work in three tabs: |
| 661 | |
| 662 | - **Overview:** pull requests merged, open pull requests and issues |
| 663 | opened, and your most recent activity. |
| 664 | - **Pull requests** and **Issues:** everything you opened, and what g1t |
| 665 | opened for you, newest first, |
| 666 | with filters beside the list for state (open, closed, merged), type, |
| 667 | repository and sort order. Add `?tab=pulls&state=merged` and the like to |
| 668 | link to a filtered list. |
| 669 | |
| 670 | **Edit it** in [Settings → Profile](https://g1t.sh/settings/profile). Every |
| 671 | field is optional. The bio takes up to 160 characters and is also what a |
| 672 | link to your profile says. The website must be an `https://` address; |
| 673 | `example.com` is saved as `https://example.com`. Your email address is |
| 674 | never shown. |
| 675 | |
| 676 | **Time zone.** Pick the time zone you are in, by city or region (such as |
| 677 | `America/Denver`), and the [card over your name](#the-card-over-a-name) |
| 678 | shows your local time, so people can tell whether it is a good moment to |
| 679 | ask you something. If your browser's time zone differs from the one |
| 680 | saved, the field offers **Use my browser's time zone**. Choose **Not |
| 681 | shown** to clear it. |
| 682 | |
| 683 | **Who sees what.** A profile is public, but the work and workspaces on it |
| 684 | are filtered for whoever is looking: |
| 685 | |
| 686 | | On the profile | Shown to a visitor when | |
| 687 | | --- | --- | |
| 688 | | An issue or pull request, and its title | They can read its repository: it is public, or they are a member of its workspace | |
| 689 | | The counts | Only what they could see is counted | |
| 690 | | A workspace | They are a member of it too, or you made a public project in it, whose page shows that already | |
| 691 | |
| 692 | Someone signed out sees your public work and the workspaces where you made |
| 693 | a public project; nothing else. The link preview for a profile uses only |
| 694 | public work. |
| 695 | |
| 696 | ### The card over a name |
| 697 | |
| 698 | Hold the pointer over a person's name or picture anywhere on g1t, or move |
| 699 | the keyboard focus to their name, and a card opens with their profile at a |
| 700 | glance: |
| 701 | |
| 702 | | On the card | Shown when | |
| 703 | | --- | --- | |
| 704 | | Picture, name, username and pronouns | Always | |
| 705 | | Bio and location | They filled them in | |
| 706 | | Their local time, such as **3:42 PM local time** | They set a [time zone](#profiles) | |
| 707 | | **Member of** | The same workspaces their profile shows you, at most three named | |
| 708 | | **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 | |
| 709 | |
| 710 | On a touch screen no card opens: a tap goes to the profile. `@g1t` has a |
| 711 | card of its own, about putting g1t to work. `ghost`, which stands in for |
| 712 | deleted accounts, has no card. |
| 713 | |
| 714 | ### Commits and your account |
| 715 | |
| 716 | A commit shows as yours, with your username, picture, profile link and |
| 717 | card, when its author address is one of your |
| 718 | [confirmed addresses](/guides/authentication/#email-addresses) or your |
| 719 | noreply address. This holds everywhere a commit appears: the Files page, |
| 720 | history, a commit, blame, branches, tags, comparisons and the |
| 721 | Contributors list, which counts every address of yours as one person. |
| 722 | |
| 723 | To have commits made on your own machine show as yours without publishing |
| 724 | your address, commit with your noreply address: |
| 725 | |
| 726 | 1. Open [Settings → Emails](https://g1t.sh/settings/emails) and copy your |
| 727 | noreply address. It looks like |
| 728 | `<8 characters of your account id>+<username>@users.noreply.g1t.sh`. |
| 729 | 2. Set it for every repository, or leave out `--global` for one: |
| 730 | |
| 731 | ```sh |
| 732 | git config --global user.email "6c1d0efg+sam@users.noreply.g1t.sh" |
| 733 | ``` |
| 734 | |
| 735 | 3. Commit and push as usual. Commits you made before keep the address they |
| 736 | were made with; add that address to your account and confirm it to have |
| 737 | them show as yours. |
| 738 | |
| 739 | | A commit's address | Shown as | |
| 740 | | --- | --- | |
| 741 | | One of your confirmed addresses, or your noreply address | You | |
| 742 | | An address added to an account but not confirmed | The name in the commit | |
| 743 | | An address no account has | The name in the commit, with a plain picture, no link and no card | |
| 744 | | A deleted account's noreply address, or any of its confirmed addresses during the 30 days it can be restored | `ghost` | |
| 745 | | g1t's own (`g1t@users.noreply.g1t.sh`) | `g1t` | |
| 746 | |
| 747 | `Co-authored-by` trailers are matched the same way, and their pictures sit |
| 748 | beside the author's. An address itself is never shown on g1t. |