Update Eligibility & Blockers

Overview

When a container has an available update, drydock evaluates it against a stack of policy and trigger gates before the matching docker / dockercompose action trigger fires. Any active gate becomes a blocker. The result is exposed on every container payload as updateEligibility; the UI summarizes it on the Update action and explains it in the container's Update Status panel.

A container is eligible when an update exists and no blocker applies. What happens next also depends on the server-wide Update mode.

Global update mode

Choose the mode under Settings → General → Update mode. The setting applies to the whole Drydock server, not just the current browser or user.

Fresh installations default to manual. When an existing installation upgrades from a version with no updateMode setting, Drydock migrates it to auto so configured automatic updates do not silently stop. Changing the mode later takes effect server-wide.

In notify mode the Update Status panel leads with Notifications only — Drydock won't apply updates and keeps diagnostic conditions behind Show details. Attempts to update through Drydock are rejected; continue to use your external update tooling.

Where blockers appear

• Container table and cards — the Update action carries one compact state: ready, soft-blocked (manual override available), or hard-blocked (locked). It does not repeat every reason on the row.
• Side panel and container full-page view — the Update Status panel shows one plain-language summary followed by the active conditions. Actionable conditions open the relevant in-app update-policy, operation-history, security, or audit surface. Conditions backed by environment variables or container labels link to the corresponding configuration documentation because those values do not have an in-app editor. Time-limited conditions retain their countdown and exact lift time.
• Dashboard — Recent Updates widget — uses the same compact Update-action state as the container list.

If a container is eligible but an automatic update does not run, check that the global mode is auto and that a matching docker / dockercompose action trigger is configured to fire for that container.

What the update dialog is telling you

When you click Update on a container that has soft blockers, the confirm dialog appends them to its message:

This update is currently policy-blocked: • (one line per active condition)

Click Update anyway to override.

This is a heads-up, not a refusal. The button changes from Update to Update anyway, and clicking it applies the update immediately. Every reason listed there is a soft blocker, which by definition only defers drydock's automatic dispatch — your own manual update goes through. Cancel instead, and the container keeps waiting for the condition to clear on its own.

A hard blocker never reaches this dialog: the Update button is disabled and the API rejects the request outright.

maintenance-window-closed in the update dialog

Outside maintenance window — auto update deferred until the window opens.

Someone has set a maintenance window on this container's watcher (DD_WATCHER_{watcher_name}_MAINTENANCE_WINDOW), and right now the clock is outside it. Drydock is telling you it wouldn't have applied this update by itself yet. It has no bearing on the manual update you just asked for: click Update anyway and it runs.

Two things commonly cause this line to show up more than expected:

• The window is narrower than it looks. MAINTENANCE_WINDOW is matched minute by minute, so 0 2-3 * * * is open only at 02:00 and 03:00 for one minute each, not from 2 AM to 4 AM. Use * 2-3 * * *. See Watchers — Maintenance window.
• The timezone isn't yours. The window is evaluated in MAINTENANCE_WINDOW_TZ, which defaults to UTC.

This is also independent of the maturity gate. A candidate can be past its maturity soak and still sit outside the maintenance window: maturity decides whether the build is old enough to trust, the window decides when drydock is allowed to act.

Reasons reference

Common scenarios

"Auto-update isn't firing on any of my compose-managed containers"

Almost always trigger-not-included — docker and dockercompose action triggers default to AUTO=oninclude. Every container you want auto-updated needs a dd.action.include label that names the matching trigger.

# drydock env
- DD_ACTION_DOCKERCOMPOSE_MYSTACK_FILE=/drydock/mystack/compose.yaml

# in mystack/compose.yaml — every service that should auto-update
services:
  app:
    labels:
      - dd.action.include=mystack

If you want every container in a stack to auto-update without per-container opt-in, set AUTO=true on the trigger instead:

- DD_ACTION_DOCKERCOMPOSE_MYSTACK_AUTO=true

"Auto-update fired before, but not for this minor release"

Likely threshold-not-reached — the trigger's THRESHOLD is set to something stricter than the detected update kind. Common cases: THRESHOLD=major will skip minor/patch/digest updates; THRESHOLD=patch will skip digest-only updates.

"All my containers show 'Maturing' even though I never set a policy"

That blocker only fires when the effective maturityMode === 'mature'. Check the blocker text and policy editor for its source: a dd.updatePolicy.maturityMode=mature container label, the watcher's DD_WATCHER_{watcher_name}_MATURITY_MODE=mature default, or a UI/API override. With none of those configured, the built-in mode is all and no maturity gate applies.

"Update Status says 'Agent mismatch'"

The trigger and the container are bound to different agents. In the controller-agent topology, an action trigger only updates containers on the agent it runs on. Either configure an additional trigger on the container's agent, or merge the topology.

API

The updateEligibility object is returned on every container in GET /api/v1/containers and pushed via SSE on changes. Both paths enrich the owning watcher's live maintenance-window state, including the masked watcher state reported by remote agents. Shape:

{
  "eligible": false,
  "blockers": [
    {
      "reason": "trigger-not-included",
      "severity": "soft",
      "message": "Trigger not matched by container label dd.action.include='undefined'.",
      "actionable": true,
      "actionHint": "Adjust the `dd.action.include` / `dd.action.exclude` labels on the container.",
      "details": {
        "triggerInclude": null,
        "triggerId": "dockercompose.mystack"
      }
    }
  ],
  "evaluatedAt": "2026-04-26T14:44:00.000Z"
}

Fields:

• eligible — true only when an update exists and no blockers apply.
• blockers[].reason — one of the codes in the reasons reference above. Stable identifier; safe to switch on programmatically.
• blockers[].severity — 'hard' or 'soft'. A hard blocker prevents manual updates too: the API rejects the update request and the UI disables the Update button (e.g. security-scan-blocked, rollback-container). A soft blocker only defers automatic dispatch — manual updates still succeed, with the UI showing a confirm modal that lists the soft blockers (e.g. maturity-not-reached, snoozed).
• blockers[].message — human-readable summary, with concrete values interpolated (tag, threshold, days remaining, etc.).
• blockers[].actionable — true when a user can clear the blocker; false for terminal states (rollback-container, active-operation, no-update-available).
• blockers[].actionHint — short next-step suggestion. Used as the second line in tooltips and the Action field on full-page cards.
• blockers[].liftableAt — ISO timestamp when a time-limited blocker (snooze, maturity) will clear automatically.
• blockers[].details — reason-specific payload (skipped tag, threshold value, agent IDs, etc.). Schema is per-reason and may grow over time.
• evaluatedAt — ISO timestamp of the evaluation. Recomputed on every container update and watcher run.

For maturity blockers, the UI treats liftableAt as the gate eligibility time. It is not a guaranteed deployment timestamp: automatic actions run after a watcher observes the now-mature candidate, and maintenance windows, security checks, trigger filters, queues, or an offline agent can delay application further.

Related

• Container Actions — the surrounding action system.
• Triggers — THRESHOLD, AUTO, and per-trigger INCLUDE / EXCLUDE env vars.
• Triggers — Maturity Gate Sweep — DD_MATURITY_SWEEP_CRON and the maturity-cleared notification fired when this gate lifts.
• Watchers — Labels — dd.action.include / dd.action.exclude and the deprecated dd.trigger.* aliases.