Products and environments

A workspace describes the software it tests and where that software runs with three objects. Products and environments do not depend on each other; only a deployment joins them. Test runs target a deployment, and the secrets vault keeps each deployment's values.

Products

• slug: 2–48 lowercase letters, digits or hyphens, with no hyphen at the start or end and not a reserved Windows folder name such as con. Unique in the workspace.
• name: 1–100 characters, unique in the workspace ignoring case.
• type: website, api, cli, mobile_app, desktop_app or agent. A product becomes a website or API product only once each of its deployments has a base URL.
• description: optional, up to 200 characters.
• repository: optional, the source repository as owner/name, such as acme/storefront. Messages about a project's tickets go to agent sessions working in the repositories of the products the project changes.

Environments

• slug and name: the same rules as a product, with names up to 80 characters.
• class: production or non-production, chosen at creation and never changed. Production means real customer data, or the live system customers use. To treat a place as the other class, create a new environment.
• description: optional, up to 200 characters. emoji: optional, shown beside the name.

The class decides the vault's rules: only admins and owners write production secrets, and only a vault key reads them back. See Secrets vault and CLI.

Deployments

• One per product and environment pair, addressed as {product}/{environment}, such as storefront/staging.
• baseUrl: an http:// or https:// URL without a username, password or #fragment. A trailing slash is dropped. Required for website and API products.
• fixtureUrl: optional, the deployment's Fixture API, which test runs call to create test data and delete it when they finish. It follows the same URL rules as baseUrl. See Test runs.
• version: optional free text up to 100 characters, such as a git SHA or a tag. The server sets versionUpdatedAt whenever it changes.
• active: false while its product or its environment is archived.

Responses carry IDs as well as slugs. IDs never change; renaming a slug keeps deployments, secrets and vault key grants, and the old slug stops working.

Archive, restore and remove

Products and environments are archived, never deleted. Archiving one:

• hides it from lists unless you ask for archived objects with archived=include or archived=only;
• makes it read-only: changing it, or creating, changing or removing one of its deployments, fails with 409 and says to restore it first;
• keeps its slug and name reserved, so it can always be restored;
• makes its deployments inactive, so vault pulls for them are refused.

Restoring reverses all of this. Repeating an archive or a restore returns the object unchanged.

Removing a deployment deletes it, but its secret values stay: deploying the same pair again brings them back.

Who can change them

API

Paths are relative to https://api.clankertest.com/v1/workspaces/{slug}. Creating returns 201, removing a deployment returns 204, and every other call returns 200 with the object. PATCH changes only the fields you send, and null clears an optional field.

curl https://api.clankertest.com/v1/workspaces/acme/deployments \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product": "storefront", "environment": "production", "baseUrl": "https://shop.acme.dev" }'

CLI

Every command prints the API's JSON, uses the workspace clanker link recorded (or --workspace), and exits 2 when it is used wrongly or the request is refused. An empty value clears a field.

clanker environment create production --name Production --class production
clanker product create storefront --name Storefront --type website --repository acme/storefront
clanker deployment create storefront production --base-url https://shop.acme.dev \
  --fixture-url https://shop.acme.dev/fixtures
clanker deployment update storefront production --deployed-version "$GIT_SHA"
clanker product list --archived only
clanker product archive storefront
clanker product restore storefront

The flag is --deployed-version because --version prints the CLI's own version.

Agents

Agents use list_products, create_deployment, update_deployment and the other catalog tools, or their /agent/v1 twins. Archiving and removing are marked destructive, so clients ask before they run them.

Errors