Getting started
Concepts
Workspaces, environments, projects, services, layers and resolution.
Workspaces
A workspace holds your team's projects, environments, roles and members. The person who creates it is the owner. Everyone else joins by invitation.
Environments
Environments are defined once per workspace and apply to every project in it, so prod means the same thing everywhere. A new workspace starts with prod. Each environment has two flags:
| Flag | Meaning |
|---|---|
| Production | Marks the environment as production. Shown in red, never allows personal overrides. |
| Allow personal overrides | Lets each user override values for themselves in this environment. |
When you add an environment, the Owner and Admin roles get write on it. Every other role gets none, unless you copy permissions from an existing environment.
Projects and services
A project is usually one repository or product. A project has a Shared layer and any number of services (for example api, web, worker).
Layers and resolution
Every value lives in one layer of one environment:
| Layer | Who sees it | Typical use |
|---|---|---|
| Shared | every service in the project | SENTRY_DSN, third-party keys used everywhere |
| Service | only that service | PORT, a service-specific database URL |
| Personal | only you, only on environments that allow it | DATABASE_URL=postgres://localhost/... |
When a service reads an environment, envpass merges the layers. A later layer wins for the same key:
Shared[env] → Service[env] → Personal[env, you]Example for api in dev:
| Key | Shared | api | Yours | Result |
|---|---|---|---|---|
SENTRY_DSN |
https://sentry... |
https://sentry... (Shared) |
||
DATABASE_URL |
postgres://team |
postgres://api |
postgres://localhost |
postgres://localhost (Yours) |
PORT |
4000 |
4000 (api) |
Service tokens never receive personal overrides. A deploy always gets the team's values.
Versions and deletion
Every write creates an immutable version. The last 30 versions of each key are kept, and any of them can be restored, which adds a new version. Deleted keys can be restored for 30 days.
Audit log
Every create, update, rename, delete, reveal, pull and permission change is recorded with the actor, time, IP address and key name. Values are never written to the log. Entries are kept for 90 days.