Skip to main content

CI/CD pipelines

Everything cotctl does on your laptop, it can do unattended in a pipeline. Running it in CI/CD is what turns "a partner deploys changes by hand" into "changes are validated and deployed automatically on every merge" — repeatable, reviewable, and not dependent on anyone remembering the steps. This page shows the recommended shape and, importantly, how to handle credentials safely.

A good cotctl pipeline mirrors the manual workflow: validate on every change, apply on merge.

  1. On a pull request — run cotctl validate --dir (offline, no credentials needed). This catches schema and cross-reference errors before review.
  2. On merge to your main branch — run cotctl apply --dir -c <profile> against the target environment, optionally preceded by a --dry-run.

Because every apply is idempotent, re-running the deploy is always safe.

Handling credentials safely​

This is the part to get right. In a pipeline there's no browser to log in with, so you authenticate non-interactively — but you never put a token in your repository.

The rule: secrets live in your CI provider, never in code. Store the credentials as encrypted CI secrets (GitHub Actions secrets, GitLab CI variables, etc.) and read them from environment variables at runtime. Never commit a token, and never paste one into a YAML or script that's checked in.

Both cotctl login (browser) and cotctl login --no-browser (email/password) are interactive — they open a browser or prompt for credentials — so they aren't suitable for an unattended job on their own. You authenticate with a pre-generated API token instead, and since 0.12.0 there are two ways to hand it over.

Export the token and the environment's API URL, and cotctl runs with no profile at all:

export COTCTL_TOKEN="$CI_COTCTL_TOKEN"
export COTCTL_API_URL="https://www.cotalker.com"

cotctl apply --dir config/ --yes

There is no login step and no -c flag. Nothing is written to disk — the configuration is built in memory for that run — and the company comes from the token itself, so it cannot disagree with the credential.

Add COTCTL_COMPANY_ID to assert which company the job expects. A token belonging to another one stops the run before anything is sent, naming both ids, and exits non-zero — 2 or 1 depending on the command (see Authentication), so test for non-zero. On a job that can write, this is worth the one line:

export COTCTL_COMPANY_ID="64a1b2c3d4e5f6a7b8c9d0e1"

An expired or rejected token stops the run and names the variable. cotctl never re-authenticates from the environment and never writes your token into a profile, so a pipeline fails loudly instead of quietly continuing as somebody else.

The other way: write a profile with --token​

Use this when a single job addresses several companies, which an environment credential cannot do — it carries one token, so it carries one company. cotctl login --token registers a pre-generated token as a named profile with no terminal attached:

echo "$CI_COTCTL_TOKEN" | cotctl login \
--url https://web.cotalker.com \
--subdomain acme \
--profile acme \
--token - \
--yes \
--allow-unverified-company

Three details that decide whether this works in a real job:

  • Pipe the token in; do not pass it as a value. --token - reads standard input, and --token @<path> reads a file. A bare --token <jwt> puts the secret in the process arguments, where any process on the same host can read it — and a CI provider masks its own log, not the process table.
  • --yes is required. Without a terminal, the profile-overwrite guard fails instead of waiting for an answer that cannot arrive.
  • --allow-unverified-company is usually required too. If the token's user cannot read the company record, the company check cannot conclude, and --yes deliberately does not answer that one.

Do not name that CI secret COTCTL_TOKEN. The name is reserved as an environment credential, so exporting it changes the behaviour of every later command that omits -c — including the ones you meant to run against a different profile.

A worked example (GitHub Actions)​

This workflow validates on pull requests and deploys on pushes to main. The credentials come entirely from repository secrets:

name: Deploy Cotalker config

on:
pull_request:
push:
branches: [main]

env:
COTCTL_NO_UPDATE_CHECK: '1' # both jobs: no update notice

jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: npm install -g @cotctl/cli@0.16.0
# Offline — no credentials required
- run: cotctl validate --dir config/

deploy:
if: github.ref == 'refs/heads/main'
needs: validate
runs-on: ubuntu-latest
env:
COTCTL_TOKEN: ${{ secrets.COTCTL_API_TOKEN }}
COTCTL_API_URL: https://www.cotalker.com
COTCTL_COMPANY_ID: ${{ vars.COTCTL_COMPANY_ID }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: npm install -g @cotctl/cli@0.16.0
- run: cotctl apply --dir config/ -y

Two things to notice. There is no login step — the environment credential is the whole of the authentication, and -c is absent because the company comes from the token. And cotctl apply ... -y skips the interactive confirmation prompts, which is exactly what you want in an unattended job.

COTCTL_COMPANY_ID is a plain variable rather than a secret: a company id is not sensitive, and keeping it visible is the point — it is the line a reviewer reads to see which environment this job deploys to.

Both jobs install a pinned version, so the version that runs is the one the workflow names — without a terminal cotctl never installs an update on its own; the pin is what keeps npm install from picking up a newer release. The workflow-level COTCTL_NO_UPDATE_CHECK removes the version notice, and keeps a runner that has a terminal but no CI variable from ever being offered an update. From 0.16.0 it does not remove the lookup itself, which also brings the data-loss advisories: even the "offline" validate job queries npm once per job on a runner that starts with an empty home directory. See New cotctl versions in a pipeline.

The CI-oriented flags, and where they live​

Most of the flags that make an apply pipeline-friendly used to live only on the entity-scoped applies. Since 0.14.0 the unified cotctl apply has caught up on all but one:

FlagOnWhat it does
--jsonsurveys, properties, workflows and — new in 0.14.0 — schedules apply, and apply --dirEmits results as JSON, one object per line, to stdout. apply -f refuses it
--quiet / -qthose, plus bots / routines / webhooks apply and the unified applySuppresses the advisory warnings on stderr. On surveys, properties, workflows and webhooks apply it also drops the would-create / would-update lines; on the unified apply, the per-field diff of a --dry-run (the result lines still print). Errors still surface, and so does every destructive finding
--diff <off\|compact\|verbose>surveys, properties, workflows apply and — new in 0.14.0 — the unified apply, -f or --dirHow much per-field diff a --dry-run prints (default compact)
--fail-on-destructivesurveys apply, properties apply, workflows apply onlyExits 2 when a --dry-run finds a danger finding

--fail-on-destructive acts only together with --dry-run, and only on a danger finding: a permission list emptied whole and — since 0.14.0 — the questions a survey update would deactivate. A warn finding never changes the exit code, which is why the flag never changes it on properties apply: every finding a property can raise is a warning.

The gate is all or nothing. It cannot accept one finding and keep failing on the rest, so a question you remove on purpose fails it too: check the question the gated dry run names, then apply — a real apply ignores the flag. And an unmodified export made with 0.13.0 or earlier can fail it: that export could leave a survey's real question out, so applying it deactivates the question. Re-export with 0.14.0 first.

The unified apply prints the destructive findings in a dry run too, since 0.14.0, but has no --fail-on-destructive. So a strict per-resource gate still uses the scoped form:

# Fail the job if deploying this workflow would destroy anything
cotctl workflows apply -f workflow.yaml -c acme --dry-run --fail-on-destructive

A common pattern is: gate each sensitive kind with a scoped --dry-run --fail-on-destructive, then deploy the whole set with apply --dir.

Exit codes​

cotctl maps outcomes to five exit codes:

CodeMeaning
0Success — including a clean --dry-run and a user-cancelled prompt with nothing wrong in it
1The default failure code: an API error, a missing file or profile, and any validation failure not covered by 2
2One of three: a pre-apply validation refusal (what was refused was not sent, though other documents of the same run may have been), an export refusal (the survey could not be modelled), or a danger finding under --fail-on-destructive
3Partial apply — part of the apply was written and the run failed afterwards: resources a Workflow created, or a schedule whose cron an update stopped and whose relaunch failed
5Stopped by a data-loss advisory (since 0.16.0) — a published advisory names this cotctl version and this command, so the command did not run, --dry-run included. Update cotctl and run it again; see Data-loss advisories

cotctl logs, which writes nothing to Cotalker, gives 3 its own meaning and adds a sixth code, 4: 3 when some requested log was not delivered, and 4 when the environment's backend has no log reader yet. See logs.

2 carries three unrelated meanings, and none of them is applied uniformly across commands. Inside one command the code is unambiguous, and that is the case a script is usually in. Across commands it is not: a pipeline that runs apply and surveys export and branches on a shared $? learns that something was refused, not whether anything was written. Pin the exact command, or read the message — do not carry one command's meaning of 2 over to the next.

0.16.0 changed a few codes. A command a data-loss advisory names exits 5 without running; a partial: true Workflow the merge refuses exits 2 from workflows apply, apply -f and apply --dir (1 → 2), as a partial: true Bot, Routine, SLA or Schedule already did; slas apply and apply --dir exit 0 on an SLA they created or updated, where every SLA write ended in 1 since 0.12.0 — and apply --dir without --continue-on-error stopped there, so the files after the first SLA file were never applied: review them, or run the same apply --dir --dry-run, before the first run on 0.16.0; validate --remote exits 1 on a Survey a Workflow names that the server does not have, as apply --dry-run already did; logs get --parts stage:<key> exits 1 for a log without that stage (0 → 1); and a COTCTL_COMPANY_ID mismatch exits 2 from schedules logs, webhooks list and webhooks logs (1 → 2). A -l that is not a positive integer on schedules logs, webhooks list and webhooks logs now exits 2 before any request.

0.14.0 changed several codes. If your pipeline tests for specific values, check it against the list below. Among the moves: a survey refusal from surveys apply or apply -f (1 → 2); an SLA or schedule refusal (1 → 2); a partial workflow apply from apply -f (1 → 3); a Workflow naming a Survey the server lacks (3 → 1, refused before its first write); bots apply --dry-run on a runtime failure (2 → 1); apply --dir without -y when its preview finds an error (now exits with that error's code, writing nothing); apply --dir for a document its own apply command refuses with 2 (1 → 2, even after --continue-on-error applied the rest); a batch that declares a resource twice (now 2, where the last document used to win); users / jobtitles apply on an inactive record whose YAML omits isActive (2 → 0, and the rest of the YAML is now written); bots, routines, users and jobtitles apply on a failure that refuses nothing in the YAML, such as a catalog that cannot be read (2 → 1); a system JobTitle code typed back wrong at its prompt in jobtitles apply or apply -f (2 → 0, cancelled like a declined prompt; apply --dir stops there with 1); and a Workflow state machine reusing a deactivated one's code (now 2, before anything is written).

Which refusals exit 2​

A kind gets the same code from its own command as from cotctl apply:

  • Survey, User and JobTitle exit 2 for what they check before writing — schema, references, a renamed code — through apply -f as through surveys, users and jobtitles apply. A check the server keeps them from making (a pinned User id it fails to look up, a JobTitle it fails to read) exits 1.
  • AccessRole, PropertyType, Property and Workflow exit 1 for theirs, through apply -f as through roles, property-types, properties and workflows apply — except a Workflow state machine whose code a deactivated state machine holds, which every command refuses with 2, and, since 0.16.0, a partial: true Workflow that is not valid once merged with the stored one, which exits 2.
  • Webhook, Routine, Bot, SLA and Schedule — which apply -f does not take — exit 2 from their own commands for what the YAML gets wrong: the schema, an SLA whose state machine or states don't resolve, a schedule's invalid cron, a bot version or routine the catalog doesn't have. A catalog that cannot be read exits 1.
  • cotctl validate exits 1 for a validation failure, not 2 — which surprises most people wiring up their first gate, because validate is the command whose whole job is validation.

Four refusals cross the kinds: an id that is not a 24-character hex ObjectId (since 0.15.0) exits with the kind's own code — 2 for a User or Survey, 1 for an AccessRole, Property, PropertyType or Workflow — dry runs included; a batch that declares a resource twice exits 2 from every apply; a bot stage missing a data entry its bot type requires exits 2 from every command that writes stages, workflows apply included; and a partial key no command reads exits 2 from apply -f but 1 from roles, property-types, properties and workflows apply.

apply --dir gives each document the code its own command gives it, and exits with the first of 3, 2, 1 it met — even after --continue-on-error applied the other files. A file it cannot read at all (a YAML syntax error, an unreadable file:// reference, a refused partial key) exits 1.

2 from surveys export is the odd one​

It is not a pre-apply signal at all: surveys export exits 2 when the simplified format cannot model the survey, and nothing was ever going to be mutated, because the run is a read.

Read inside that command, though, it is unambiguous and it is actionable. It has exactly one meaning — this survey cannot be expressed in the simplified format — and exactly one answer: re-run with --format raw, which exports the survey in its stored shape (see Export & import). A script wrapping surveys export can branch on 2 and retry without reading the message. (An unknown --format value is not that: since 0.14.0 it exits 1 before anything is read.)

One failure whose code depends on the command you entered through​

An inconsistency in the current implementation, not a design. Pin the exact command in a script rather than relying on the code alone.

Script-bot refusal — the YAML declares a PBScript, CCJS or ESMCode stage without --allow-script-bots. Same refusal, same message, two codes:

CommandExit
cotctl bots apply2
cotctl routines apply2
cotctl slas apply1
cotctl schedules apply1
cotctl workflows apply1
cotctl apply -f1
cotctl apply --dirthe document's own command: 2 for a Bot or a Routine, 1 otherwise

A partial apply no longer depends on the entry point: since 0.14.0 a workflow left half-applied exits 3 from apply -f, apply --dir and workflows apply -f alike — --rollback included, since what it deactivates stays on the server, inactive — and a schedule whose cron relaunch failed exits 3 from schedules apply and apply --dir. What --rollback deactivated is reported as rolled back — created, then deactivated ([rolled-back] under --dir, "action": "rolled-back" under --json), not as created.

stdout vs. stderr​

cotctl keeps the two streams disciplined so your pipeline can parse output reliably:

  • stdout carries the result — the human table, or, under --json, the JSON-Lines payload and nothing else. When you pass --json, the human banner is suppressed so stdout stays machine-parseable.
  • stderr carries warnings, progress notes, and prompts. Since 0.14.0 that includes the confirmation prompt and Apply cancelled. under --json (surveys, workflows, properties and schedules apply, and apply --dir), so a run without -y no longer mixes them into the JSON lines.

So the safe pattern in CI is to capture stdout for parsing and let stderr flow to the log:

cotctl workflows apply -f workflow.yaml -c acme --dry-run --json > result.jsonl
# parse result.jsonl; warnings and progress already went to the job log via stderr

Token lifetime in CI​

An ApiToken does not expire from disuse. It carries its own expiry date, set when it was issued — or none at all, for a token issued from the webclient's ApiTokens panel — and a pipeline that runs once a quarter is as valid as one that runs hourly. The "7 days of inactivity" rule belongs to the browser session a person logs in with, not to the token a pipeline uses.

What that means in practice: an ApiToken that has an expiry date expires on a date somebody chose, and nothing warns you as it approaches. Record when each one expires and rotate it before that date — a pipeline whose only credential has lapsed fails on its next run, which is usually the run you needed.

cotctl tells you which token it is refusing: an expired environment credential stops the run naming COTCTL_TOKEN before the token is sent, and a 401 names the API URL it was sent to — usually a revoked token, or one from another environment than COTCTL_API_URL. The token must be an ApiToken: since 0.15.0 a COTCTL_TOKEN without a type claim of api-token is refused before any request, so replace a session JWT, or an ApiToken old enough to predate the claim, with a fresh ApiToken.

New cotctl versions in a pipeline​

From 0.14.0, cotctl checks for a newer version before every command. In a pipeline that check never prompts and never installs anything: without a terminal, or with CI set to any value other than empty, 0, false or no — and on any command run with -y — it writes a few [cotctl] lines to stderr (the versions, the release notes link for a breaking update, and the command to update with) and runs the command as usual. stdout is untouched, so --json output stays parseable. 0.14.0 is the first version with the check: a job still on 0.13.x never sees a notice.

Two settings make a job predictable:

  • Pin the version you install — npm install -g @cotctl/cli@<version>, as the worked example does. An unpinned install picks up whatever is latest on the next run, breaking releases included: 0.14.0, for one, changed several exit codes a pipeline may branch on. Move the pin when you have read the release notes.
  • Set COTCTL_NO_UPDATE_CHECK=1 to turn the update notice off. Any value other than empty, 0, false or no turns it off.

From 0.16.0, one thing the variable does not turn off: data-loss advisories. When a published advisory names the pinned version and a command the job runs, that command does not run — --dry-run included — and exits 5, after naming the loss and the version that fixes it on stderr. The lookup that brings the advisories still runs at most once every 12 hours while ~/.cotctl can be written — once per job on a runner that starts with an empty home directory — and waits up to 1.5 seconds where npm cannot be reached. A job that meets exit 5 moves its pin to the fixed version and runs again; to run the affected version anyway, set COTCTL_ACCEPT_ADVISORY to the id the message names (several ids separated by commas or spaces). A job pinned to a version before 0.16.0 never meets exit 5: those versions do not read advisories.

To move a pinned job forward, change the pin. Outside a pipeline, cotctl update installs the latest version on demand — see update.

Use --continue-on-error deliberately​

By default, a directory apply stops at the first failure — usually what you want, so a broken deploy halts loudly. Add --continue-on-error only when you intentionally want the remaining entities to apply despite one failing; the run still exits non-zero. It exists only on apply --dir: apply -f refuses it with exit 1. In an unattended job, which runs with -y, the interactive preview never runs — see apply for what it changes when a person answers the prompt.

See also​