Known Issues

Cleanup-Environments must be triggered manually or wired to a Jenkins cron trigger. The library does not schedule it. If no one runs it, envs with expired TTL stay on disk and continue consuming runner capacity.

Workaround: add a time-based trigger (triggers { cron('H 4 * * *') }) to the Cleanup-Environments job, or schedule it via the multibranch / organisation folder pipeline that owns it.

createEnvStep runs DFS cycle detection over the effective depends_on graph. On a cycle it prints a warning and continues; Compose itself refuses to start on circular depends_on.

Workaround: treat the warning as a build error. The small window where a cycle is desirable (because service_healthy breaks it) is rare — inspect the warning explicitly when it fires.

deployEnvStep assumes every online non-master agent has:

There is no pre-flight check. A missing tool produces a failure deep inside docker compose up -d or the port-scan step.

Workaround: include a one-liner check in agent provisioning (yq --version && docker compose version).

Scripts that are not yet approved in Manage Jenkins → In-process Script Approval render the fallback HTML silently. There is no banner, no console message, no System Log line unless you filter on ScriptApproval.

Workaround: always check approval first when a panel suddenly shows the fallback.

If createEnvStep fails after meta.json is written (rare, but possible during a docker compose build crash), the env directory stays behind in state configured with status: failed. The name is then reserved and utils.validateEnvName(…​, checkExists=true) rejects it.

Workaround: Manage-Environment → delete on the failed env, or remove ${MASTER_ENVS_DIR}/<env> manually.

Compose bind mounts expand ${DATA_FOLDER:-.} relative to the docker-compose.yml. Setting DATA_FOLDER=/opt/qa-envs/foo via the Active Choices form works but silently duplicates the absolute path for every bind mount and breaks on the runner if the master ever renders a path that does not exist there.

Workaround: leave DATA_FOLDER unset unless you have a specific reason. The default (the env’s own directory) is almost always right.

atomicWriteMeta protects against torn reads, not against two admins submitting manage-owners at the same second. The last submission wins.

Workaround: manage-owners is low-frequency by nature; if it matters, coordinate on Slack or gate the action behind a Jenkins lock.