Environments and secrets

Settings that differ between stages, such as endpoints, timeouts or credentials, do not belong in a component. Store them in an environment and reference them from your components. The same agent can then run in test and in production with different settings.

Use variables in components

Components use variables with the syntax ${VARIABLE_NAME}:

{
  "config": {
    "base_url": "${TICKET_API_URL}",
    "timeout": "${TICKET_API_TIMEOUT}"
  }
}

The values are filled in from the environments of the deployment when the agent is loaded.

Create an environment

POST ${RUNTIME_BASE_URL}/v1/environments
Content-Type: application/json

{
  "name": "production",
  "variables": {
    "TICKET_API_URL": "https://tickets.example.com",
    "TICKET_API_TIMEOUT": "30",
    "TICKET_API_KEY": "${secret:TICKET-API-KEY}"
  }
}

Variable keys use uppercase letters, digits and underscores, and start with an uppercase letter.
Updating an environment replaces all its variables.
An environment cannot be deleted while a deployment uses it.

Combine several environments

A deployment can use several environments. They are merged in the order they are listed, and later environments override earlier ones:

Environments: ["base", "regional"]

base:      TICKET_API_URL=https://tickets.example.com, TIMEOUT=30
regional:  TICKET_API_URL=https://eu.tickets.example.com

Result:    TICKET_API_URL=https://eu.tickets.example.com, TIMEOUT=30

A common pattern is one base environment with shared settings and one environment per stage with the differences.

Secrets

Credentials such as API keys and passwords are stored as secrets. Secrets are stored separately for each tenant and are never visible to other tenants. Their values cannot be read back through the API.

Store a secret

POST ${RUNTIME_BASE_URL}/v1/secrets
Content-Type: application/json

{
  "name": "TICKET-API-KEY",
  "value": "the-secret-value"
}

If a secret with this name already exists, its value is replaced. The response contains only the name and updated_at.

Secret names may contain letters, digits and dashes, up to 127 characters. Underscores are not allowed.

Use a secret

Reference a secret with ${secret:SECRET-NAME}, either as the value of an environment variable or directly in a component:

{ "TICKET_API_KEY": "${secret:TICKET-API-KEY}" }

Manage secrets

Operation	Request
List secrets (names and dates only)	`GET /v1/secrets`
Get metadata of one secret	`GET /v1/secrets/{name}`
Check whether a secret exists	`HEAD /v1/secrets/{name}`
Delete a secret	`DELETE /v1/secrets/{name}`