g1t/apps/docs/src/content/docs/guides/workspaces.md
| 1 | --- |
| 2 | title: Workspaces |
| 3 | description: Workspaces, members and roles, 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 | It cannot be changed later, because repository addresses and clones |
| 19 | depend on it. |
| 20 | 3. Optionally give it a display name. |
| 21 | |
| 22 | From the API, `POST /workspaces` with `slug` and `name`, or the |
| 23 | `create_workspace` tool: |
| 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 `whoami`, lists the |
| 33 | ones you belong to. |
| 34 | |
| 35 | Usernames and workspaces share one set of names, so a name means the same |
| 36 | thing wherever it appears. Your username is reserved for you: only you can |
| 37 | create a workspace with that name, and nobody can register a username that |
| 38 | is already a workspace. |
| 39 | |
| 40 | ## Members and roles |
| 41 | |
| 42 | | Role | Can | |
| 43 | | --- | --- | |
| 44 | | Member | Create repositories, push, manage issues, merge pull requests, plan work, put g1t agents to work, and see the workspace's usage and billing. | |
| 45 | | Owner | Everything a member can, and manage members, the workspace's access tokens, its details, and add credit. | |
| 46 | |
| 47 | Whoever creates a workspace is its owner. An owner adds people on the |
| 48 | workspace's **Settings → Members** page by their g1t username; they join as |
| 49 | members. An owner can also remove a member there. |
| 50 | |
| 51 | ## The workspace's pages |
| 52 | |
| 53 | A workspace's page, `g1t.sh/<workspace>`, shows its repositories and the |
| 54 | pull requests in progress across them. In the sidebar, its members also |
| 55 | have **Usage**, what g1t agents have cost (see |
| 56 | [usage and billing](/guides/usage-and-billing/)), and **Settings**, which |
| 57 | slides the sidebar over to the workspace's settings: |
| 58 | |
| 59 | | Settings | Who | | |
| 60 | | --- | --- | --- | |
| 61 | | **General** | Owners | The display name and a one-line description. | |
| 62 | | **Members** | Members | Who belongs, and their roles. Owners add and remove people. | |
| 63 | | **Billing** | Members | The balance and statement. Owners add credit. | |
| 64 | | **Integrations** | Members | [Model providers, alerts and trackers](/guides/integrations/). Owners connect and remove them. | |
| 65 | | **Access tokens** | Members | The workspace's own tokens. Owners create and delete them. | |
| 66 | |
| 67 | The arrow at the top of the settings goes back. |
| 68 | |
| 69 | ## Workspace access tokens |
| 70 | |
| 71 | A workspace has access tokens of its own, for CI, integrations and agents |
| 72 | that work for a team. They replace the shared "service account" other |
| 73 | forges need: there is no extra account to create, pay for or lose the |
| 74 | password to. |
| 75 | |
| 76 | | | Personal token | Workspace token | |
| 77 | | --- | --- | --- | |
| 78 | | Belongs to | You | The workspace | |
| 79 | | Acts as | You | The workspace: its name is the author of what it does | |
| 80 | | Can reach | Every workspace you belong to | That workspace only | |
| 81 | | Can do | Everything you can | What a member can; it cannot manage people, tokens or workspaces | |
| 82 | | When its creator leaves | Stops working | Keeps working | |
| 83 | | Created by | You, in [Settings](https://g1t.sh/settings) | An owner, under the workspace's **Settings → Access tokens** | |
| 84 | |
| 85 | They are the same kind of token and are sent the same way; see |
| 86 | [access tokens](/guides/authentication/#access-tokens). With git, any |
| 87 | username works; the token is the password. `GET /user` answers with |
| 88 | `"kind": "workspace"` for one, and `"kind": "user"` for a personal token. |
| 89 | |
| 90 | Every member can see a workspace's tokens: the name, who created each and |
| 91 | when it was last used. Only owners can create or delete them. |