Usage

Operator view of the Jenkins jobs exposed by this library. For the state machine see Lifecycle; for who is allowed to run what see RBAC.

Every job uses the first-run handler: the first invocation exits after writing parameter definitions. Refresh the job page and click Build with Parameters to actually run it.

Create-Environment

Job: QA-Environments/Create-Environment.

Parameters

  • ENV_NAME — auto-generated from constellation names (QAConfig.Names.CONSTELLATIONS) plus a numeric suffix. Can be edited; must match ^[a-z0-9][a-z0-9-]{2,49}$. May start with a digit (commit 83b82f9).

  • DATABASE_TYPE — mysql / oracle / postgres. Drives oneOf resolution in the dep graph.

  • SELECTED_SERVICES — multi-select checkboxes. Mandatory services pre-checked from dependencies.yaml. Services flagged disablechange are locked.

  • IMAGE_VERSIONS — per-service Docker tag selector, populated from Harbor / Docker Hub at parameter-render time.

  • GLOBAL_VARIABLES — rich textarea that overlays onto resources/services/.env.<db>. Preserves comments and blank lines (commit-safe rewrites via utils.updateEnvVariables).

  • SERVICE_VARIABLES — per-service .env editor. In create mode starts from the file defaults; see qaUiScripts — Build-time Active Choices Factory.

  • TTL — 1d / 3d / 1w / 1m / 2m / 3m / 1y / infinity.

  • ALLOW_MISSING_DEPS — opt-in checkbox; appears only when utils.findMissingMandatoryDeps reports gaps.

  • DEBUG — keeps failed envs on disk for investigation. Independent from QA_LOG_VERBOSE.

  • IPV6_ENABLED — enable IPv6 on the environment’s Docker network. Default off. Create-time only — the flag is fixed at create and stored in meta.json (ipv6_enabled); to change it, clone or re-create the env (Update-Environment has no IPv6 parameter, by design). When on, deployEnvStep overrides the compose default network with enable_ipv6: true (subnet auto-assigned from the daemon’s IPv6 default-address-pools) and runs an agent-side IPv6 preflight. The chosen DEPLOY_RUNNER must be IPv6-onboarded (see IPv6 environments) — kernel IPv6 enabled, daemon.json ipv6+ip6tables+IPv6 default-address-pools, and Node Property QA_AGENT_IPV6_READY=true — or the deploy fails fast. meta.ipv6_enabled is not a supported manual-edit surface: hand-editing it on a deployed env re-introduces a Docker "network needs to be recreated" error on the next compose up.

    Enabling IPv6 changes the host-side exposure of published ports. All service ports publish as bare HOST:CONTAINER, so on a daemon with ipv6+ip6tables Docker installs IPv6 DNAT rules and the ports become reachable on the agent’s IPv6 addresses — bypassing any IPv4-only host firewall. Only onboard internet-facing agents for IPv6 after extending their IPv6 firewalling accordingly.
Output

  • Rendered bundle under MASTER_ENVS_DIR/<env>/: docker-compose.yml, .env.<db>, per-service .env, meta.json (status configured).

  • Quota check: non-admin users are capped at QAConfig.Limits.MAX_ENVS_PER_USER (default 5). Admins are exempt.

Deploy-Environment

Job: QA-Environments/Deploy-Environment.

Parameters

  • ENV_NAME — dropdown of configured / stopped envs visible to the current user.

  • DEPLOY_RUNNER — online agents only, master / built-in excluded. Last known runner is pre-selected from meta.runner.

  • DRY_RUN — boolean. When true, pipeline runs everything up to compose up -d and reports actions without starting containers (181ec01 introduced strict boolean parsing).

Output

  • Port-conflict check on the runner via ss -H -ltn. utils.findPortOwners names the offender when a collision happens.

  • docker compose up -d on the runner; meta.runner + meta.status = deployed written via atomicWriteMeta.

  • Access URLs banner: host FQDN + mapped ports (commit 2137e56).

Update-Environment

Job: QA-Environments/Update-Environment.

Change services, versions, or variables without redeploying. The renderer strips Compose profiles: from services that are being started so they actually run (commit cc8566b).

Parameters

  • ENV_NAME — dropdown.

  • DATABASE_TYPE — switch via switchDatabaseStep if it actually changes.

  • SELECTED_SERVICES — add / remove services (ownership-gated).

  • IMAGE_VERSIONS, GLOBAL_VARIABLES, SERVICE_VARIABLES.

  • DEPLOY_RUNNER — migrate to another agent if selected.

  • CHANGE_DIFF (derived) — live HTML diff summarising pending changes in FINAL_PREVIEW.

Output

  • Re-rendered bundle + a compose up -d --remove-orphans where needed.

  • meta.json gets last_action = update, last_action_at = <now>.

To migrate a stopped env onto a different runner, re-run Deploy-Environment with a new DEPLOY_RUNNER. There is no separate "restore" job — Manage-Environment → ACTION=start brings an env up on its recorded runner; a runner change needs Deploy.

Manage-Environment

Job: QA-Environments/Manage-Environment. A single dispatcher for every post-create lifecycle action and ownership change. There are no standalone Stop-Environment, Delete-Environment, or Restore-Environment jobs in v2.6.0 — everything they used to do is now an ACTION on Manage-Environment.

Parameters

  • ENV_NAME — dropdown.

  • ACTION — radio: start, stop, restart, delete, manage-owners. Disabled entries depend on current status (e.g. start is disabled when already deployed).

  • OWNERS_LIST, OWNERS_PREVIEW — shown only when ACTION=manage-owners.

  • CREATE_BACKUP, CONFIRM — shown only when ACTION=delete.

Table 1. Outcomes by action
Action Effect

start

compose start on the recorded runner. State → deployed. Used to bring a stopped env back up — this is the "restore" path.

stop

compose stop. State → stopped. Volumes preserved.

restart

compose restart. State unchanged.

delete

Optional pre-delete backup via utils.createSnapshot, then compose down -v, then rm -rf of the env directory. State → deleted.

manage-owners

Rewrites meta.owners[]. Containers untouched. Skips the duplicate-audit code path that the other actions go through (commit 867752a).

Manage Owners

Appears only when ACTION=manage-owners.

Parameters

  • OWNERS_LIST — CascadeChoiceParameter + PT_CHECKBOX of Jenkins logins (commit e48fa6d). Currently saved co-owners are pre-checked; check to grant, uncheck to revoke. The creator (meta.created_by) is not in the list and always retains access.

  • OWNERS_PREVIEW — live HTML diff (added vs removed). Display-only.

Effect on meta.json
{
  "created_by": "alice",         // immutable
  "owners":     ["bob", "carol"] // rewritten from OWNERS_LIST
  // other fields untouched
}

For the full RBAC matrix and limits (MAX_OWNERS_PER_ENV, admin bypass, cron behaviour) see RBAC & Ownership.

List-Environments

Job: QA-Environments/List-Environments. Table of envs with status, TTL, runner, created-by, image tags. Non-admins see only their own or co-owned envs; admins see everything.

Cleanup-Environments

Job: QA-Environments/Cleanup-Environments. TTL-based sweep; RBAC-aware. Must be triggered manually or via a cron trigger — not scheduled by default. See Known Issues.

DEBUG vs QA_LOG_VERBOSE

These are two independent switches. Either, both, or neither can be on.

Flag Where What it does

DEBUG

Create-Environment parameter

Keeps a failed env directory on disk so you can inspect it. Does not affect logs.

QA_LOG_VERBOSE

Jenkins global env var

Switches the logging DSL into verbose mode (see Logging DSL). Does not affect env lifecycle.