Environments
Create and change Environments, including variables, secret files, repos, versions, and upgrades.
An Environment is a versioned bundle of variables, secret files, and repos that Docks start with; see Environments. Routes return the Environment object. Every change to the bundle makes a new version. Shared rules are in Conventions.
Every route except the list and create routes takes :ref, an Environment id or
name, and organizationId as a query parameter:
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
organizationId (query) | uuid | when :ref is a name | Organization the name is resolved in. Ignored when :ref is an id. |
Reads need org role member; every write and secrets:reveal need admin.
Secret values are never returned except by secrets:reveal.
Variable names match [A-Za-z_][A-Za-z0-9_]*, at most 128 characters, may not
start with DOCK_, and may not be one of a few platform-reserved names. Two
writes that race for the same new version fail with conflict (409); retry. An Environment holds at most 100 variables (64 KB) and 20
secret files (256 KB each, 1 MB total).
GET /v1/environments
List an organization's Environments.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
organizationId (query) | uuid | yes | Organization to list. |
Response: an array of Environment objects. Errors:
validation_error, organization_not_found.
POST /v1/environments
Create an Environment (201), starting as an empty version 1. Role: admin.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
organizationId | uuid | yes | Owning organization. | |
name | string | yes | 2 to 64 lowercase letters, digits, dash, underscore | Unique per organization. |
secretsAccess | string | no | members or admins, default admins | Who can launch Docks that receive this Environment's secrets, files, and credentials. |
Response: the Environment object. Errors:
validation_error, organization_not_found, environment_name_taken.
GET /v1/environments/:ref
Read one Environment.
Response: the Environment object. Errors:
environment_not_found.
PATCH /v1/environments/:ref
Rename an Environment, move the default, or change its posture. Role: admin.
Posture changes make a new version. Every field is optional.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
name | string | no | 2 to 64 lowercase letters, digits, dash, underscore | New name; Docks that use it follow the rename. |
isDefault | boolean | no | true makes it the organization default. false is refused on the current default; make another one default instead. | |
secretsAccess | string | no | members or admins | Who can launch Docks that receive its secrets. |
safeForThirdParties | boolean | no | Withhold everything the pass flags would send, for Docks other people drive. Overrides the other switches. | |
passGithub | boolean | no | Clone the selected repos into Docks. | |
passSecrets | boolean | no | Write the Environment's variables and secret files into Docks. | |
passDockCredentials | boolean | no | Give each Dock a DOCK_API_KEY that acts as its creator; it is rotated on every apply and revoked with the Dock. | |
passAgentsCredentials | boolean | no | Fill missing agent keys from the organization's provider keys. |
Response: the Environment object. Errors:
validation_error, environment_not_found, environment_name_taken.
DELETE /v1/environments/:ref
Delete an Environment. Role: admin. The last remaining Environment cannot be
deleted; if the default is deleted, the oldest remaining one becomes the default.
Response: { "deleted": true }. Errors: validation_error (the only
Environment), environment_not_found.
GET /v1/environments/:ref/versions
List the Environment's versions, newest first.
Response: an array of { "version": 3, "createdAt": "...", "dockCount": 2 }.
dockCount is the number of Docks pinned to that version. Errors:
environment_not_found.
POST /v1/environments/:ref/upgrade
Move Docks pinned to an older version to the current version (202). Role:
admin.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
dockIds | array of uuid | no | Docks that use this Environment | Limit the move to these Docks; omitted moves every older Dock. |
Response: { "operation": { ... } }, an operation.
Errors: validation_error, environment_not_found, dock_not_found.
GET /v1/environments/:ref/repos
List the repos the Environment clones into new Docks.
Response: an array of the repos entries of the Environment object.
Errors: environment_not_found.
POST /v1/environments/:ref/repos
Add a repo (201). Role: admin.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
provider | string | yes | github or gitlab | Where the repo lives. |
repositoryId | string | yes | 1 to 128 | The provider's repository id. |
fullName | string | yes | owner/name | Repository to clone. |
baseBranch | string | no | max 128 | Branch to check out. |
setupScript | string | no | max 65536 bytes | Script run in the repo after cloning. |
Response: the Environment object. Errors:
validation_error, environment_not_found, conflict (the repo is already
added, or another repo clones into the same folder).
DELETE /v1/environments/:ref/repos/:repoId
Remove a repo. Role: admin.
Response: the Environment object. Errors:
environment_not_found, not_found (no such repo).
PUT /v1/environments/:ref/secrets
Replace all variables and secret files at once. Omitted parts are dropped, not
merged. Role: admin.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
envContents | string | no | KEY=value lines; blank lines and # comments skipped | Variables as dotenv text. |
secretFiles | array of { path, contents } | no | at most 20 files | Secret files; path is relative to the repo, never absolute. |
Response: the Environment object. Errors:
validation_error, environment_not_found.
POST /v1/environments/:ref/vars
Set one variable. Role: admin.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
key | string | yes | name rules above | Variable name. |
value | string | yes | Variable value. |
Response: the Environment object. Errors:
validation_error, environment_not_found.
DELETE /v1/environments/:ref/vars/:key
Remove a variable. Role: admin.
Response: the Environment object. Errors:
environment_not_found, not_found (no such variable).
POST /v1/environments/:ref/files
Set one secret file. Role: admin.
| Field | Type | Required | Limits / default | Description |
|---|---|---|---|---|
path | string | yes | 1 to 256, relative, no .., not under .dock/ | File path. |
contents | string | yes | max 256 KB | File contents. |
Response: the Environment object. Errors:
validation_error, environment_not_found.
DELETE /v1/environments/:ref/files/:path
Remove a secret file. Role: admin.
Response: the Environment object. Errors:
environment_not_found, not_found (no such secret file).
POST /v1/environments/:ref/secrets:reveal
Return the plaintext variables and secret files of the current version. Role:
admin.
Response:
{
"envContents": "API_TOKEN=abc\n",
"secretFiles": [ { "path": ".env.local", "size": 12, "contents": "KEY=value\n" } ]
}Errors: environment_not_found.