add digest pinning support for compose

Author: Crow-Control

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Compose label-driven docker-compose trigger configuration** — Added support for container labels to create and scope compose triggers from discovered containers, including `dd.compose.file` / `wud.compose.file` and compose trigger options (`backup`, `prune`, `dryrun`, `auto`, `once`, `threshold`).
 - **Compose-file digest update support** — Docker-compose trigger now supports digest-pinned image references in compose files (`image@sha256:...` and `image:tag@sha256:...`) so digest-based services can be updated without dropping pinning.
+- **Compose forced digest pinning toggle** — Added `digestpin` support for docker-compose triggers so compose image updates can be written as `tag@digest` when a replacement digest is available. Includes per-container labels (`dd.compose.digestpin` / `wud.compose.digestpin`) and watcher-level defaults (`DD_WATCHER_{name}_COMPOSE_DIGESTPIN`) for generated compose triggers.
 
 - **Compose-native auto-compose discovery** — Added `dd.compose.native` / `wud.compose.native` container labels to enable deriving compose file paths from native Compose labels (`com.docker.compose.project.config_files` + `com.docker.compose.project.working_dir`) when `dd.compose.file` is not set. This requires the resolved compose path to exist inside the drydock container (same path context used by `docker compose`).
 - **Watcher-wide compose-native default** — Added `DD_WATCHER_{name}_COMPOSE_NATIVE=true` to enable compose-native path discovery for all containers watched by a Docker watcher, with per-container `dd.compose.native` still taking precedence.

README.md

@@ -405,6 +405,7 @@ When using the Docker Compose trigger, container labels can override trigger set
 | `dd.compose.dryrun` | `wud.compose.dryrun` | `DD_TRIGGER_DOCKERCOMPOSE_xxx_DRYRUN` | `true` / `false` |
 | `dd.compose.auto` | `wud.compose.auto` | `DD_TRIGGER_DOCKERCOMPOSE_xxx_AUTO` | `true` / `false` |
 | `dd.compose.once` | `wud.compose.once` | `DD_TRIGGER_DOCKERCOMPOSE_xxx_ONCE` | `true` / `false` |
+| `dd.compose.digestpin` | `wud.compose.digestpin` | `DD_TRIGGER_DOCKERCOMPOSE_xxx_DIGESTPIN` | `true` / `false` |
 | `dd.compose.native` | `wud.compose.native` | `DD_WATCHER_<WATCHER_NAME>_COMPOSE_NATIVE` | `true` / `false` |
 | `dd.compose.threshold` | `wud.compose.threshold` | `DD_TRIGGER_DOCKERCOMPOSE_xxx_THRESHOLD` | `all` / `major` / `minor` / `patch` |
 
@@ -413,6 +414,7 @@ Behavior notes:
 - `dd.compose.file` / `wud.compose.file` causes drydock to create (or reuse) a scoped `dockercompose` trigger for that container.
 - That generated compose trigger is set with `requireinclude=true` and auto-appended to the container include list, so it only runs for explicitly associated containers.
 - `dd.compose.native` / `wud.compose.native` enables deriving compose file paths from native Compose labels (`com.docker.compose.project.config_files` and `com.docker.compose.project.working_dir`).
+- `dd.compose.digestpin` / `wud.compose.digestpin` forces compose image updates to write `tag@digest` when the update digest is known.
 - Compose-native/automatic detection requires the resolved compose file path to be valid inside the drydock container (same path that `docker compose` uses); if Compose was run from a host-only path, bind-mount that path into drydock at the same location or set `dd.compose.file` explicitly.
 - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_NATIVE=true` enables compose-native lookup by default for all containers in that watcher (container label can still override).
 - If `dd.compose.auto` is omitted, normal trigger default applies (`auto=true`).
@@ -423,6 +425,7 @@ Behavior notes:
   - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_DRYRUN`
   - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_AUTO`
   - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_ONCE`
+  - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_DIGESTPIN`
   - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_NATIVE`
   - `DD_WATCHER_<WATCHER_NAME>_COMPOSE_THRESHOLD`
   These defaults apply when corresponding compose labels are not present.

app/triggers/providers/dockercompose/Dockercompose.test.ts

@@ -174,6 +174,7 @@ describe('Dockercompose Trigger', () => {
     trigger.configuration = {
       dryrun: true,
       backup: false,
+      digestpin: false,
       composeFileLabel: 'dd.compose.file',
     };
 
@@ -591,6 +592,37 @@ describe('Dockercompose Trigger', () => {
     expect(dockerTriggerSpy).toHaveBeenCalledWith(container);
   });
 
+  test('processComposeFile should force digest pinning for tag updates when digestpin is enabled', async () => {
+    trigger.configuration.dryrun = false;
+    trigger.configuration.backup = false;
+    trigger.configuration.digestpin = true;
+    const container = makeContainer({
+      tagValue: '1.0.0',
+      updateKind: 'tag',
+      remoteValue: '1.1.0',
+      result: {
+        digest: 'sha256:newdigest',
+      },
+    });
+
+    vi.spyOn(trigger, 'getComposeFileAsObject').mockResolvedValue(
+      makeCompose({ nginx: { image: 'nginx:1.0.0' } }),
+    );
+
+    const { writeComposeFileSpy, dockerTriggerSpy } = spyOnProcessComposeHelpers(
+      trigger,
+      'image: nginx:1.0.0',
+    );
+
+    await trigger.processComposeFile('/opt/drydock/test/stack.yml', [container]);
+
+    expect(writeComposeFileSpy).toHaveBeenCalledWith(
+      '/opt/drydock/test/stack.yml',
+      'image: nginx:1.1.0@sha256:newdigest',
+    );
+    expect(dockerTriggerSpy).toHaveBeenCalledWith(container);
+  });
+
   test('processComposeFile should skip update when compose is digest-pinned but tag update has no remote digest', async () => {
     trigger.configuration.dryrun = false;
     trigger.configuration.backup = false;
@@ -1634,4 +1666,32 @@ describe('Dockercompose Trigger', () => {
       keptPinned: true,
     });
   });
+
+  test('buildUpdatedComposeImage should force pinning for non-digest compose images when enabled', () => {
+    const result = testable_buildUpdatedComposeImage(
+      'nginx:1.0.0',
+      'nginx:2.0.0',
+      { kind: 'tag', remoteValue: '2.0.0' },
+      'sha256:newdigest',
+      true,
+    );
+    expect(result).toEqual({
+      image: 'nginx:2.0.0@sha256:newdigest',
+      keptPinned: true,
+    });
+  });
+
+  test('buildUpdatedComposeImage should fall back when forced pinning has no digest available', () => {
+    const result = testable_buildUpdatedComposeImage(
+      'nginx:1.0.0',
+      'nginx:2.0.0',
+      { kind: 'tag', remoteValue: '2.0.0' },
+      undefined,
+      true,
+    );
+    expect(result).toEqual({
+      image: 'nginx:2.0.0',
+      keptPinned: false,
+    });
+  });
 });

app/triggers/providers/dockercompose/Dockercompose.ts

@@ -49,8 +49,15 @@ function normalizeImageWithoutDigest(image) {
   return normalizeImplicitLatest(imageWithoutDigest);
 }
 
-function buildUpdatedComposeImage(currentImage, fallbackImage, updateKind, remoteDigest) {
-  if (!currentImage?.includes('@')) {
+function buildUpdatedComposeImage(
+  currentImage,
+  fallbackImage,
+  updateKind,
+  remoteDigest,
+  forceDigestPin = false,
+) {
+  const currentImageIsDigestPinned = Boolean(currentImage?.includes('@'));
+  if (!currentImageIsDigestPinned && !forceDigestPin) {
     return {
       image: fallbackImage,
       keptPinned: false,
@@ -60,13 +67,20 @@ function buildUpdatedComposeImage(currentImage, fallbackImage, updateKind, remot
   const digestToPin =
     updateKind?.kind === 'digest' ? updateKind?.remoteValue : (remoteDigest ?? undefined);
   if (!digestToPin) {
+    if (!currentImageIsDigestPinned) {
+      return {
+        image: fallbackImage,
+        keptPinned: false,
+      };
+    }
     return {
       image: undefined,
       keptPinned: false,
     };
   }
 
-  const imageToPin = updateKind?.kind === 'digest' ? currentImage : fallbackImage;
+  const imageToPin =
+    updateKind?.kind === 'digest' && currentImageIsDigestPinned ? currentImage : fallbackImage;
   const { imageWithoutDigest } = splitDigestReference(imageToPin);
   return {
     image: `${imageWithoutDigest}@${digestToPin}`,
@@ -189,6 +203,7 @@ class Dockercompose extends Docker {
       // Make file optional since we now support per-container compose files
       file: this.joi.string().optional(),
       backup: this.joi.boolean().default(false),
+      digestpin: this.joi.boolean().default(false),
       // Add configuration for the label name to look for
       composeFileLabel: this.joi.string().default('dd.compose.file'),
     });
@@ -566,11 +581,13 @@ class Dockercompose extends Docker {
     }
 
     const currentImage = serviceToUpdate.image;
+    const forceDigestPin = `${this.configuration.digestpin}`.trim().toLowerCase() === 'true';
     const digestAwareUpdate = buildUpdatedComposeImage(
       currentImage,
       this.getNewImageFullName(registry, container),
       container.updateKind,
       container.result?.digest,
+      forceDigestPin,
     );
     const updateImage = digestAwareUpdate.image;
 

app/watchers/providers/docker/Docker.test.ts

@@ -604,6 +604,7 @@ describe('Docker Watcher', () => {
             'dd.compose.file': '/tmp/my-stack/docker-compose.yml',
             'dd.compose.auto': 'true',
             'dd.compose.prune': 'false',
+            'dd.compose.digestpin': 'true',
           },
           triggerInclude: 'ntfy.default:major',
         },
@@ -621,6 +622,7 @@ describe('Docker Watcher', () => {
         '/tmp/my-stack/docker-compose.yml',
         {
           auto: 'true',
+          digestpin: 'true',
           prune: 'false',
         },
       );
@@ -653,6 +655,7 @@ describe('Docker Watcher', () => {
         compose: {
           threshold: 'minor',
           auto: false,
+          digestpin: true,
         },
       });
 
@@ -663,6 +666,7 @@ describe('Docker Watcher', () => {
         '/tmp/my-stack/docker-compose.yml',
         {
           auto: 'false',
+          digestpin: 'true',
           threshold: 'minor',
         },
       );
@@ -1314,6 +1318,7 @@ describe('Docker Watcher', () => {
             'dd.compose.backup': 'true',
             'dd.compose.prune': 'false',
             'dd.compose.auto': 'true',
+            'dd.compose.digestpin': 'true',
             'dd.compose.threshold': 'minor',
           },
         },
@@ -1337,6 +1342,7 @@ describe('Docker Watcher', () => {
           backup: 'true',
           prune: 'false',
           auto: 'true',
+          digestpin: 'true',
           threshold: 'minor',
         },
       );

app/watchers/providers/docker/Docker.ts

@@ -37,6 +37,7 @@ import Watcher from '../../Watcher.js';
 import {
   ddComposeAuto,
   ddComposeBackup,
+  ddComposeDigestpin,
   ddComposeDryrun,
   ddComposeFile,
   ddComposeNative,
@@ -58,6 +59,7 @@ import {
   ddWatchDigest,
   wudComposeAuto,
   wudComposeBackup,
+  wudComposeDigestpin,
   wudComposeDryrun,
   wudDisplayIcon,
   wudDisplayName,
@@ -110,6 +112,7 @@ export interface DockerWatcherConfiguration extends ComponentConfiguration {
     dryrun?: boolean;
     auto?: boolean;
     once?: boolean;
+    digestpin?: boolean;
     native?: boolean;
     threshold?: string;
   };
@@ -257,6 +260,13 @@ function getDockercomposeTriggerConfigurationFromLabels(
     dockercomposeConfig.once = once;
   }
 
+  const digestpin =
+    getLabel(labels, ddComposeDigestpin, wudComposeDigestpin) ||
+    normalizeComposeDefaultValue(composeDefaults.digestpin);
+  if (digestpin !== undefined) {
+    dockercomposeConfig.digestpin = digestpin;
+  }
+
   const threshold =
     getLabel(labels, ddComposeThreshold, wudComposeThreshold) ||
     normalizeConfigStringValue(composeDefaults.threshold);
@@ -1178,6 +1188,7 @@ class Docker extends Watcher {
           dryrun: this.joi.boolean(),
           auto: this.joi.boolean(),
           once: this.joi.boolean(),
+          digestpin: this.joi.boolean(),
           native: this.joi.boolean(),
           threshold: this.joi.string(),
         })

app/watchers/providers/docker/label.ts

@@ -111,6 +111,12 @@ export const wudComposeAuto = 'wud.compose.auto';
 export const ddComposeOnce = 'dd.compose.once';
 export const wudComposeOnce = 'wud.compose.once';
 
+/**
+ * Optional dockercompose trigger forced digest pinning mode (true | false).
+ */
+export const ddComposeDigestpin = 'dd.compose.digestpin';
+export const wudComposeDigestpin = 'wud.compose.digestpin';
+
 /**
  * Optional auto-compose discovery mode (true | false).
  * When enabled, use compose-native labels to derive compose file path.