Portainer

The portainer trigger lets Drydock apply tag updates to Portainer-managed Docker Compose stacks while keeping Portainer as the stack owner. It is a controller-local action: Portainer triggers are not registered in agent mode and cannot update containers discovered through an agent.

Portainer compatibility is intentionally narrow. The container must have non-empty com.docker.compose.project and com.docker.compose.service labels. Generic Docker containers, containers with only partial Compose labels, digest-only updates, stacks Portainer does not report as standalone Compose stacks, Drydock's own container, and containers marked dd.update.mode=infrastructure are rejected by the Portainer trigger. Configure a Docker action alongside Portainer when Drydock itself or infrastructure containers need the normal Docker self-update transition. Drydock pulls the image locally and runs the signature check and the vulnerability scan against the digest that pull fetched, then tells Portainer to redeploy with image pulling disabled so it deploys from the local image instead of resolving the tag again. Portainer performs the container create, not Drydock. Under a required post-pull identity binding policy (signature verification on, or availability policy other than warn), what Drydock hands Portainer is pinned to the bound repo:tag@sha256:... reference instead of the mutable tag, the same way DIGESTPINNING=true does for the Compose action, so the create is anchored to what the gate scanned rather than to whatever the tag resolves to at that moment. The pin follows the update mode: compose mode rewrites the service's image: line to the pinned reference, while env mode leaves the stack file alone and writes the digest into the version env variable as tag@sha256:..., so the rendered image is the pinned reference and the stack keeps its ${VAR} template. If no identity could be bound under required, the update is refused before Portainer is asked to do anything. Enable DIGESTPINNING explicitly to pin under an optional or disabled policy too; there a pin that cannot be expressed logs a warning and redeploys unpinned instead of failing the update. Left unpinned, the binding is checked after the fact rather than enforced at create time: if the tag moves in the meantime and Portainer creates a container whose image ID is not the scanned one, the redeploy never converges and that unscanned container keeps running until DD_ACTION_PORTAINER_{trigger_name}_REDEPLOYTIMEOUT expires, five minutes by default. Drydock then attempts to restore the previous stack, and a restore that fails as well is reported in the error rather than swallowed. Swarm and Kubernetes stacks are refused before the stack file is fetched and before anything is pulled, because their nodes pull the tag themselves and a scan on the controller says nothing about what the cluster runs. Portainer disables Drydock's automatic rollback monitor. Its normal lifecycle backup metadata is retained for history, but a Portainer-originated backup is rejected by the inherited Docker stop-remove-recreate rollback path; Docker-originated backups remain manually rollback-able when a Docker action is configured.

The trigger will:

• Resolve the Portainer stack from the container's Compose labels, using dd.portainer.stack-id only to disambiguate matching stacks
• Fetch the current Portainer stack file and stack env
• Update either a stack env variable or the service image in the stack file
• Ask Portainer to redeploy the stack using the locally pulled and scanned image
• Run the normal Drydock update lifecycle gates around that redeploy

Variables

This trigger also supports the common configuration variables.

The env var keys for ALLOWHTTP, UPDATEMODE, VERSIONVARLABEL, UPDATEMODELABEL, PRUNESTACK, and DIGESTPINNING are case-insensitive. The camelCase forms are accepted too.

Labels

Update Modes

auto is the default. Drydock inspects the service image in Portainer's stack file:

• If the image tag is declared as an env variable such as pihole/pihole:${PIHOLE_TAG:-2026.05.0}, and that variable is referenced nowhere else in the Compose file, Drydock updates the Portainer stack env variable and leaves the compose file unchanged.
• If the image tag is hardcoded such as pihole/pihole:2026.05.0, Drydock patches only the target service's image value in the Portainer stack file.

env updates a Portainer stack env variable only when the selected variable is referenced exclusively by the selected service's image tag. References in another service, another image, or any other Compose value fail closed. Set dd.portainer.version-var to name the variable when it is not detected, but the selected service image must still use that variable as its tag. The stack file is never rewritten in this mode, digest pinning included: a pinned redeploy sets the variable to tag@sha256:... rather than replacing the ${VAR} reference with a literal image, so the stack stays an env template and stays in env mode on the next cycle. Git-backed stacks, including stacks with GitOps metadata, aren't supported by the file-stack update path.

compose always patches the service image in the Portainer stack file. The patch uses the same service-scoped, formatting-preserving compose mutation helper as the Docker Compose trigger.

Example

services:
  drydock:
    image: codeswhat/drydock
    environment:
      - DD_ACTION_PORTAINER_LOCAL_URL=https://portainer.lan
      - DD_ACTION_PORTAINER_LOCAL_APIKEY__FILE=/run/secrets/portainer_api_key
      - DD_ACTION_PORTAINER_LOCAL_AUTO=oninclude
      - DD_ACTION_PORTAINER_LOCAL_UPDATEMODE=auto

For a stack service using a Portainer env variable:

services:
  pihole:
    image: pihole/pihole:${PIHOLE_TAG:-2026.05.0}
    labels:
      dd.watch: "true"
      dd.action.include: "portainer"
      dd.portainer.version-var: "PIHOLE_TAG"

When Drydock updates the container, Portainer's stack env receives the new PIHOLE_TAG, and Portainer redeploys the stack.