The object graph
Read it as: an organization contains workspaces; a workspace contains projects and environments side by side; a runtime is created for a project, into an environment; each runtime has one live runtime instance at a time; a session happens inside an instance.
Projects and environments are siblings
This is the single relationship most worth getting right, because the UI's grouping can suggest otherwise.
- A project is what code: a repository or a base image, plus its settings.
- An environment is where it runs: a Docker host or a Kubernetes cluster.
- A runtime is the join: this project, in that environment, right now.
An environment carries no link to a project. You can run any project in any environment in the same workspace, and running project A in an environment does not reserve it or configure it for project A. That is the point: one team's build server serves every project the team has.
Organization in the UI, company in the API
The UI says Organization. The API says company — company_uuid, scope=company,
/api/v1/companies/.... Nothing else in the model has two names, so once you know this one you can
read API responses without translating.
What is scoped where
| Thing | Lives at | Notes |
|---|---|---|
| Members and roles | Organization (and workspace) | Company roles plus per-workspace roles — see Security |
| Git connections | Organization | Assigned to the workspaces allowed to use them |
| Integrations | Organization and personal | Two different things with one name — see Integrations |
| Projects | Workspace | |
| Environments | Workspace | |
| Controllers | Environment | Self-registering |
| Agent definitions | Organization, workspace or project | Innermost wins — see precedence |
| Secrets | Organization, workspace or project | Optionally pinned to one environment |
| Runtimes, sessions | Project × environment |
Next
- Workspace · Project · Environment — the three you meet in the first ten minutes, in depth.
- Configuration precedence — the other hierarchy.