Skip to content

Releases

v0.5.0 — Coolify 4.7.5, safer writes, hardened redaction

Choose a tag to compare

@Coriou Coriou released this 16 Nov 19:19

Verified against Coolify 4.7.5 (latest stable; two live instances, read-only). Tested range:
4.5.0 – 4.7.5. What changed in Coolify and what the API still cannot do:
docs/coolify-api-coverage.md.

Install (pnpm, or Bun) from the tag, or from the attached tarball when the machine has no git:

pnpm add -D coolify-harness@github:Coriou/coolify-harness-api#v0.5.0
pnpm add -D https://github.com/Coriou/coolify-harness-api/releases/download/v0.5.0/coolify-harness-0.5.0.tgz
bun add -d coolify-harness@github:Coriou/coolify-harness-api#v0.5.0
bun add -d https://github.com/Coriou/coolify-harness-api/releases/download/v0.5.0/coolify-harness-0.5.0.tgz

Needs Node.js >= 24 (or Bun). No install script runs.

Upgrading from 0.4.x

No command or flag was removed. The config file is unchanged, with one condition: the instance
url must be the final address (redirects are no longer followed). Check these:

  • env delete on Coolify ≥ 4.7 needs a token with the delete ability (a Coolify change).
  • config doctor now calls Coolify (GET /version) and exits non-zero when a token is set
    but rejected (5), the instance cannot be reached or is not a Coolify (1), or no token is set at
    all (5). --offline does the local check only; it too exits 5 when the instance or target
    named on the command line has no token, and a config whose target points at an unknown
    instance is exit 2 (both were exit 0).
  • The instance url must not redirect (http → https, another host): the request fails and
    says so. Put the final URL in the config.
  • deploy --wait can now end with exit 7 or 8 where it ended with 0: when Coolify skips the
    request because that commit is already queued or building, the wait reports on that deployment
    instead of returning at once (exit 1 when it cannot tell which one, 5 without read).
  • A plain deploy of an application makes one more request (GET /deployments/{uuid}, at
    most 10 s, needs read; without it the check is skipped) and exits 1 with DEPLOY_NOT_QUEUED
    when Coolify answered "queued" for a deployment it does not have.
  • env delete --key refuses a value holding = or a blank (it is not a name), and a key that
    was not found is echoed (text and notFound in the JSON) only when it reads like a variable
    name: otherwise it is <N-character key>. An unreadable --from-file / --token-file path
    is described the same way when it does not read like a path.
  • A deploy interrupted (Ctrl-C, SIGTERM) while it checks or waits exits 130 with its document;
    a deploy Coolify did not queue leaves two audit records (the request, then its failure).
  • flag set --redeploy without --apply no longer deploys, and flag set without --set /
    --from-file is a usage error (it was a bare deploy with --redeploy --apply).
  • --preview on a service or a database is exit 2 (it wrote the production row); --take 0 and
    numbers that are not plain digits are exit 2.
  • A request now times out after 30 s (it could hang for ever); an unterminated quote in a
    --from-file is exit 2.
  • --from-file strips the quotes around a value. The first env diff --from-file after
    upgrading lists the keys 0.4 wrote with their quotes as updates; applying fixes them.
  • Variable names are validated (letters, digits, _, .): a bad name is exit 2 before any
    request, instead of a half-applied write.
  • compose get / compose set need read:sensitive (they printed an empty document without it),
    and so does env delete on a service or a docker-compose application (it reads the compose to
    check the key is not referenced; --force skips the check).
  • database set --public true on a database that has no port stored is exit 2: add --public-port.
  • compose set, proxy set, database set, env apply --json: confirmed may be null (the
    re-read failed). compose set --from-file / proxy set --from-file refuse a file without a
    top-level services:; proxy set refuses --image together with --from-file (the image was
    silently dropped).
  • env diff --json / env apply --json: every value is redacted (they were printed in clear).
  • If you parse env apply --json / flag set --json: it is now ONE document (plan + dryRun,
    applied, confirmed); it used to be JSON followed by prose. With --redeploy the deploy
    acknowledgement is its deploy field, not a second document.
  • status / logs --build: the latest deployment is the latest production one (a
    pull-request preview on top of the list is skipped).
  • Library: invalid input raises InvalidInputError, not a ZodError; DEFAULT_LATEST_TAKE is 1.
    Network failures are CoolifyNetworkError (not the runtime's TypeError). applyEnvWrite
    returns { confirmed: false, confirmError } when the re-read fails (it threw). upsertEnvs
    refuses is_preview items on a service or database, and a key with edge whitespace.
    waitForDeployment defaults changed: the interval grows from 2 s to 5 s, 5 failed polls are
    tolerated (was 3), a 4xx is fatal at once, and NaN or negative timeoutMs / intervalMs /
    pollGraceMs / maxConsecutiveErrors throw a RangeError; getLatestDeployment prefers a
    production row.

Security

  • env diff --json and env apply --json printed env values in clear: the desired values
    (creates[].value, updates[].value) and, on a key with duplicate rows, the LIVE values
    (duplicateKeyDrift[].values). Every value in a plan is now [REDACTED] (N chars). Human
    output was never affected.
  • Redaction bypasses closed. A compose with Windows line endings (CRLF) was not redacted at
    all. Also now covered: quoted keys and JSON-style compose, flow mappings, a list at the indent
    of environment:, anchors, values spanning lines (block scalars with indicators, a value on the
    next line, multi-line quoted scalars), PEM blocks, every value under environment: whatever the
    key case, command: / entrypoint: / test: and Dockerfile RUN / ENV / ARG (flags such as
    --requirepass x, -a x, -pSECRET, -u user:pass, header values, export token=…),
    requirepass / http_Passwd style directives in *_conf documents, Traefik / Caddy auth
    labels, URL passwords after an empty user or containing @, ?password= query parameters,
    token-only URLs, Bearer tokens in Coolify's own format, and everything nested under a
    sensitive key. The compose diff redacts each document as a whole.
  • The API token can no longer reach an error message: a token with a line break is refused
    without being quoted, and the runtime's own message is scrubbed.
  • Redirects are not followed, so a token or a request body never travels to another address.
  • A --set argument without =, a stray argument, an invalid variable name and a malformed
    dotenv line are described in errors, never quoted (they are often a secret out of place).
  • Server error messages are sanitised before they reach stderr or the audit log: anything that
    repeats a value or a line of a document sent in the request, URL credentials and tokens.
  • --out FILE refuses to write through a symlink and sets mode 0600 before writing; the audit
    log is 0600 (also when an older version created it).
  • The config refuses an instance URL with credentials and a tokenEnv that is not a variable name.
  • Found by six rounds of adversarial review and covered by test/redaction-*.test.ts: the
    value of a flag on the next list item or continuation line, command lists read one argument
    at a time (block and flow style), quoted -pSECRET, header flags, Bearer / Basic tokens,
    $(…) and backtick substitutions, quoted parts glued by the shell, values nested under a
    sensitive key, scalars folded or quoted over several lines, lone CR line breaks, comments,
    Dockerfile continuations, -e name=value and leading shell assignments whatever the case,
    build args: and x-…environment blocks, password hashes, webhook URLs, Go DSNs, PEM blocks
    with armor headers, pasted between quotes, written out by a command over several lines, as a
    JSON array of lines, or of any length. Every scan is linear in the input (several patterns took
    seconds to minutes on a hostile 100 kB line).
  • Redaction also had to stop hiding what a reviewer must see. A PEM marker used to hide
    everything up to the next END marker, or the rest of the document: put in a label, a list item,
    a flow collection or a comment, it hid a new privileged: true or a docker.sock mount from a
    compose set diff. A marker now hides only what a key block is made of — base64 lines and the
    armor headers (Proc-Type, DEK-Info, Version, Comment…) — up to its END marker; any
    other line is shown, minus the rows of the key it may hold (after a header of an unknown name,
    or written one echo '…' >> key per row, the long base64 rows are still hidden). An env item
    holding a lone quote no longer hides what follows; flow-style volumes:
    are shown; a service named test or env, set -e, sed -e, - shared_buffers=256MB
    arguments and the lines that continue an inline command: stay readable.
  • compose set and proxy set say how many added or changed lines their diff shows as
    [REDACTED] (hiddenAddedLines with --json, a NOTE: line otherwise) and where to read
    them: a hidden line is a change nobody reviewed. A lone CR inside a diff line is printed as
    \r instead of overprinting the line.
  • What the redactor does not claim: it is a heuristic over text, not a parser. A password given
    as a bare positional argument (rabbitmqctl add_user u PASS), in free prose, or under a
    lower-case key that says nothing (pw, k) is not recognised. Keep secrets in env variables
    and reference them ($VAR): references are always shown, values never.
  • A --key NAME=value given to env delete, a value after --token-file, --timeout or
    --public, and a...
Read more

v0.4.1 — null env values on Coolify 4.7

Choose a tag to compare

@Coriou Coriou released this 16 Nov 09:29

Verified against Coolify 4.7.5 (two live instances, read-only).

Install from the attached tarball (no git needed, no script runs):

pnpm add -D https://github.com/Coriou/coolify-harness-api/releases/download/v0.4.1/coolify-harness-0.4.1.tgz
bun add -d https://github.com/Coriou/coolify-harness-api/releases/download/v0.4.1/coolify-harness-0.4.1.tgz

From the git tag: bun add -d coolify-harness@github:Coriou/coolify-harness-api#v0.4.1. pnpm refuses this
version from git (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED: it still has a prepare script, removed in
0.5.0), so with pnpm use the tarball.

Fixed

  • env list / env diff / env apply / env delete failed with Coolify response (listEnvs) failed contract validation on Coolify 4.7. Coolify 4.7.5 stores a compose-declared blank
    variable (${VAR:-}) with no value and serialises value: null (also real_value: null,
    order: null); the read schema only accepted a string or an absent key. value is now
    nullish: a null value reads as '' and the row carries value_null: true.
    • A null value is not a withheld one. value_hidden still means only "the token lacks
      read:sensitive" (key absent); env diff / env apply are refused (exit 5) for withheld
      values only.
    • A null row compares equal to an empty desired value: KEY= in --from-file / --set KEY=
      against a null row is unchanged, never an update, and a null row next to an empty-string row
      of the same key and scope is not duplicate-key drift.
    • env list prints len=0 (null) and --json rows gain value_null (boolean, additive);
      value_length stays null for withheld values only.

Added

  • EnvVar.value_null (optional in the type, always set by the parser).
  • test/fixtures/coolify/v4.7/envs-compose-blank.json: synthetic, 4.7.5-shaped env payload.

Full changelog: v0.4.0...v0.4.1