Command

The command trigger lets you run arbitrary commands upon container update notifications.

logo

The command trigger lets you run arbitrary commands upon container update notifications.

Variables

Env var	Required	Description	Supported values	Default value when missing
`DD_ACTION_COMMAND_{trigger_name}_CMD`	🔴	The command to run
`DD_ACTION_COMMAND_{trigger_name}_SHELL`	⚪	The shell to use	Any valid installed shell path	`/bin/sh`
`DD_ACTION_COMMAND_{trigger_name}_TIMEOUT`	⚪	The command timeout (in ms)	Integer `>= 0` (`0` means no timeout)	`60000`
`DD_ACTION_COMMAND_{trigger_name}_ENV`	⚪	Additional parent environment variable names to pass through to the subprocess	Comma-separated list of key names (e.g. `KUBECONFIG,DOCKER_HOST`)	(none)

This trigger also supports the common configuration variables. Update information is passed as environment variables (see below).

Security: DD_ACTION_COMMAND_{trigger_name}_CMD is executed as {shell} -c {cmd} with drydock process privileges. This is an intentional admin-only feature configured through environment variables (not API-exposed). Use only trusted command strings and validate any interpolated values.

Environment isolation (v1.5.0+): The subprocess no longer inherits the full drydock process environment. Only a restricted set of standard shell variables (PATH, HOME, TMPDIR, TMP, TEMP, LANG, LC_ALL, TZ, USER, SHELL) is inherited from the parent, along with all drydock-provided container variables. DD_* secrets (registry tokens, OIDC credentials, agent tokens, etc.) are excluded by default. Use DD_ACTION_COMMAND_{trigger_name}_ENV to explicitly pass any additional parent environment variable your script needs.

Container-derived values injected as environment variables are automatically sanitized before being passed to the subprocess. In any scalar value sourced from container metadata (image name, tags, labels, etc.), these are replaced with _:

the shell metacharacters `, $, ;, &, |, <, >, (, )
whitespace, which would otherwise split one value into several arguments
the globbing characters *, ?, [, ], {, }, ~, and the quoting characters \, ", '
control characters and DEL

A leading - is removed entirely, so a value can never parse as a command-line option. Note that this means a dd.display.name containing spaces reaches your script with underscores in place of them.

container_json, containers_json, dd_title and dd_body keep their spaces and quotes: the JSON has to stay pipeable into jq, and the digest title and body are message text. Static values configured directly in CMD are not modified.

Always double-quote expansions in your command. Write echo "$${display_name}", not echo $${display_name}. The sanitizer removes what would split or glob a scalar value, but quoting is what actually makes an expansion a single argument, and the JSON and message variables are deliberately left unscrubbed for spaces.

Migration note (upgrading from pre-v1.5.0)

Before v1.5.0, the subprocess inherited the entire drydock process environment, including every DD_* secret. Starting in v1.5.0, only a restricted allowlist is passed by default.

If your command script depends on additional environment variables from the drydock process (for example, KUBECONFIG or a custom DOCKER_HOST), add them to the ENV option:

DD_ACTION_COMMAND_LOCAL_ENV=KUBECONFIG,DOCKER_HOST

Standard shell variables (PATH, HOME, etc.) are always included and do not need to be listed.

Environment variables passed to the executed command

In simple mode (execution per container to update)

display_icon
display_name
id
image_architecture
image_created
image_digest_repo
image_digest_value
image_digest_watch
image_id
image_name
image_os
image_registry_name
image_registry_url
image_tag_semver
image_tag_value
name
result_tag
status
update_available
update_kind_kind
update_kind_local_value
update_kind_remote_value
update_kind_semver_diff
watcher

This list is not exhaustive. The simple-mode subprocess also receives every other field of the runtime container object flattened to snake_case keys, including labels, security-scan data, update-policy state, and dependency info, whatever that particular container currently carries. Treat the list above as the stable core set, not the full schema.

Example

display_icon='mdi:docker'
display_name='test-nginx-1'
id='94f9f845de0fc4f8ad17c0ee1aaeaf495669de229edf41cdcd14d2af7157e47e'
image_architecture='amd64'
image_created='2023-06-13T07:15:33.483Z'
image_digest_repo='sha256:b997b0db9c2bc0a2fb803ced5fb9ff3a757e54903a28ada3e50412cc3ab7822f'
image_digest_value='sha256:b997b0db9c2bc0a2fb803ced5fb9ff3a757e54903a28ada3e50412cc3ab7822f'
image_digest_watch=false
image_id='sha256:7d3c40f240e18f6b440bf06b1dfd8a9c48a49c1dfe3400772c3b378739cbdc47'
image_name='library/nginx'
image_os='linux'
image_registry_name='hub.public'
image_registry_url='https://registry-1.docker.io/v2'
image_tag_semver=true
image_tag_value='1.25.0'
name='test-nginx-1'
result_tag='stable-alpine3.20-slim'
status='running'
update_available=true
update_kind_kind='tag'
update_kind_local_value='1.25.0'
update_kind_remote_value='stable-alpine3.20-slim'
update_kind_semver_diff='major'
watcher='local'

In addition, a container_json environment variable is passed containing the full container entity as a JSON string.

In batch mode (execution for a batch of containers to update)

A containers_json environment variable is passed containing the array of all the containers to update as a JSON string. When the batch has a digest title or body to report, dd_title and dd_body are also passed; when the batch run has a known event kind, dd_event_kind is passed too. All three are omitted when the corresponding value is empty.

Examples

Running an arbitrary command

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_ACTION_COMMAND_LOCAL_CMD=echo "$${display_name}" can be updated to "$${update_kind_remote_value}"

Running a custom bash script

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_ACTION_COMMAND_LOCAL_CMD=bash -c /drydock/trigger.sh
    volumes:
      - ${PWD}/drydock/trigger.sh:/drydock/trigger.sh

Command

On this page