Watchtower Release Notes

Overview

This is a patch that is intended to integrate fixes to Watchtower's handling of local images and also Shoutrrr's handling of authentication for Matrix notifications.

Fixes

fix(digest): skip registry requests for locally built images by @nicholas-fedor in #1514

Dependency Updates

chore(deps): update google.golang.org/genproto/googleapis/api digest to f93e5f3 by @renovate[bot] in #1510

chore(deps): update module github.com/nicholas-fedor/shoutrrr to v0.14.3 by @renovate[bot] in #1513

chore(deps): update google.golang.org/genproto/googleapis/rpc digest to 3a24fdc by @renovate[bot] in #1515

Full Changelog: v1.16.0...v1.16.1

Original source Report a problem

Overview

Release 1.16.0 introduces new advanced features, a number of bug and security-related fixes, and several dependency updates.

You are highly encouraged to review Watchtower's documentation if you are utilizing advanced features, such as the HTTP API, and/or are interested in using new, experimental features, such as the ephemeral self-updates or image cooldowns.

Important

Watchtower's HTTP API now explicitly requires using POST requests for the /v1/update endpoint and GET requests for the /v1/metrics endpoint.

Rate limiting has also been introduced and can be configured to better fit your use case.

Bug fixes include, but aren't limited to, improvements to error handling, race conditions, retry logic for Docker daemon connection issues, port conflicts, and self-update cleanup. In the event of authentication failures during image pulls, warnings will be propagated to users via notifications. This may potentially result in increased noise in the event of misconfigured registries.

If you're using Watchtower without any advanced features, then you should see a slight performance improvement when Watchtower is checking images and a deduplication of "Found new image" and "Removing image" notification entries.

Note

Given the nature of the new features and number of changes being released, please reference the Discussion's Support section for v1.16.0 support before creating new bug reports.

Features

feat: add ephemeral self-update capability by @nicholas-fedor in #1491

feat: add image cooldown supply-chain defense mechanism by @nicholas-fedor in #1495

feat: add HTTP API rate limiting and security improvements by @nicholas-fedor in #1505

Bug Fixes

fix: handle container removed between check and stop by @nicholas-fedor in #1475

fix: replace fragile string-based error checking with typed errors by @nicholas-fedor in #1476

fix: differentiate auth, not-found, and transient errors during image pull by @nicholas-fedor in #1477

fix(container): validate port bindings before ContainerCreate by @nicholas-fedor in #1478

fix: replace global image inspect mutex with per-image keyed mutex by @nicholas-fedor in #1479

fix: prefer Watchtower-labeled container when multiple share hostname by @nicholas-fedor in #1480

fix: skip self-update when exposed ports would cause conflict by @nicholas-fedor in #1481

fix: make excess Watchtower cleanup non-fatal with increased retry window by @nicholas-fedor in #1482

fix: deduplicate image removal and grouped notification entries by @nicholas-fedor in #1483

fix: retry transient Docker daemon connection failures during container listing by @nicholas-fedor in #1492

fix(api): correct self-update and add skipped container tracking in HTTP API by @nicholas-fedor in #1506

Dependency Updates

chore(deps): update module github.com/docker/cli to v29.3.1+incompatible by @renovate[bot] in #1472

chore(deps): update google.golang.org/genproto/googleapis/api digest to d5a96ad by @renovate[bot] in #1497

chore(deps): update google.golang.org/genproto/googleapis/rpc digest to d5a96ad by @renovate[bot] in #1498

chore(deps): update module github.com/nicholas-fedor/shoutrrr to v0.14.2 by @renovate[bot] in #1504

Full Changelog: v1.15.0...v1.16.0

Original source Report a problem

Overview

Version 1.15.0 of Watchtower features the addition of a global Use Docker Compose Depends-On configuration option that provides users the option to disable Watchtower's use of the Docker Compose depends_on configuration option. This minor release also integrates Shoutrrr v0.14.1, which includes an update to Matrix v3 notification support and a minor fix for Mattermost notification titles.

Feature Addition

Add option to disable Docker Compose depends_on dependency detection by @nicholas-fedor in #1457

Bug Fixes

fix: prevent cleanup of images actively used by active containers by @LJspice in #1427

fix: resolve type mismatch after a minor Shoutrrr API change by @nicholas-fedor in #1463

Dependency Updates

chore(deps): update module golang.org/x/net to v0.52.0 by @renovate[bot] in #1432

chore(deps): update module golang.org/x/tools to v0.43.0 by @renovate[bot] in #1433

chore(deps): update module go.yaml.in/yaml/v2 to v3 by @renovate[bot] in #1439

chore(deps): update google.golang.org/genproto/googleapis/api digest to d00831a by @renovate[bot] in #1445

chore(deps): update google.golang.org/genproto/googleapis/rpc digest to d00831a by @renovate[bot] in #1444

chore(deps): update module go.yaml.in/yaml/v2 to v2.4.4 by @renovate[bot] in #1440

chore(deps): update module github.com/pelletier/go-toml/v2 to v2.3.0 by @renovate[bot] in #1461

chore(deps): update module github.com/nicholas-fedor/shoutrrr to v0.14.1 by @renovate[bot] in #1462

New Contributors

@LJspice made their first contribution in #1427

Full Changelog: v1.14.4...v1.14.5

Original source Report a problem

Overview

Patch release v1.14.4 of Watchtower integrates a minor bug fix and several dependency updates, including Shoutrrr v0.14.0, which adds both MQTT and Twilio notification support.

Bug Fix

Improve graceful handling of notifications by @nicholas-fedor in #1408

Dependency Updates

• chore(deps): update module github.com/docker/cli to v29.3.0+incompatible by @renovate[bot] in #1390
• chore(deps): update dependency go to v1.26.1 by @renovate[bot] in #1393
• chore(deps): update module github.com/nicholas-fedor/shoutrrr to v0.14.0 by @renovate[bot] in #1407
• chore(deps): update module golang.org/x/text to v0.35.0 by @renovate[bot] in #1410
• chore(deps): update OpenTelemetry and golang.org/x dependencies by @nicholas-fedor in #1411

Documentation Update

Document regex pattern matching support by @nicholas-fedor in #1404

Full Changelog: v1.14.3...v1.14.4

Original source Report a problem

Overview

This patch release includes several improvements and fixes to improve Watchtower's reliability. Container operations now support proper cancellation and timeouts. Startup failures are now visible as warnings without enabling debug mode. The HTTP API now prevents concurrent update conflicts by returning HTTP 429 when an update is already running.

Note

Containers without proper stop signaling are now expected to take the full 30-second timeout period to stop, unless configured to use a different stop signal or timeout.

Bug Fixes

• Update container startup failures to log at warning level by @nicholas-fedor in #1332
• Fix context propagation to enable proper cancellation and timeout handling by @nicholas-fedor in #1335
• fix(api): return HTTP 429 for full updates when another update is running by @veeceey in #1304

Dependency Updates

• Update indirect Go dependencies by @nicholas-fedor in #1343
• chore(deps): update transitive dependencies by @nicholas-fedor in #1373

Documentation Updates

• Add status code and concurrency behavior information to HTTP API update endpoint documentation by @nicholas-fedor in #1342

New Contributors

• @veeceey made their first contribution in #1304

Full Changelog: v1.14.2...v1.14.3

Original source Report a problem

Overview

This is a patch release that integrates a fix for Watchtower's handling of container dependencies, adds two minor performance improvements, and an update to Go version 1.26.0.

Bug Fixes

• Add service-only matching for cross-project container dependencies by @nicholas-fedor in #1307

Performance Improvements

• Optimize HTTP client creation for registry authentication by @nicholas-fedor in #1287
• Improve digest matching efficiency and reliability by @nicholas-fedor in #1289

Dependency Updates

• chore(deps): update module golang.org/x/text to v0.34.0 by @renovate[bot] in #1303
• chore(deps): update dependency go to v1.26.0 by @renovate[bot] in #1309

Full Changelog

Full Changelog: v1.14.1...v1.14.2

Original source Report a problem

Overview

This is a patch release that introduces several fixes and dependency updates, including improvements to container dependency management and the Compose-based dependency handling that was introduced with version 1.13. The update to Shoutrrr v0.13.2 enables the use of Discord threads, as documented here. Watchtower's multiple notification services documentation was also updated to provide additional clarity.

Bug Fixes

• Resolve prefix matching and circular dependency issues by @nicholas-fedor in #1265
• Prevent spurious safeguard delay when SkipSelfUpdate is enabled by @nicholas-fedor in #1276
• Extract getRawLabelValue to Eliminate Code Duplication and Improve Performance by @nicholas-fedor in #1277
• Fix missing space between fields in notifications by @nicholas-fedor in #1279

Dependency Updates

• chore(deps): update module github.com/onsi/gomega to v1.39.1 by @renovate[bot] in #1261
• chore(deps): update module github.com/onsi/ginkgo/v2 to v2.28.1 by @renovate[bot] in #1262
• chore(deps): update module github.com/docker/cli to v29.2.1+incompatible by @renovate[bot] in #1274
• chore(deps): update module github.com/nicholas-fedor/shoutrrr to v0.13.2 by @renovate[bot] in #1275

Documentation Updates

• Improve multiple notification services documentation by @nicholas-fedor in #1251

Full Changelog: v1.14.0...v1.14.1

Original source Report a problem

Overview

This minor release starts off the new year with several feature additions, bug fixes, and dependency updates, including integrating Go version 1.25.6.

Version 1.14.0 introduces the automatic detection of user-configured container stop timeouts from the Docker configuration (#1182), adds support for using a file reference when specifying notification templates (#1209), and provides enhanced cron schedule support when specifying schedules with seconds (robfig/cron expression format) (#1208).

This release includes fixes for several critical bugs including self-update cleanup issues, data races in concurrent access, panics in container info handling, and improvements to dependency label processing. Self-updates are now tracked via the use of a com.centurylinklabs.watchtower.container-chain Docker container label, which provides a means of explicitly ensuring parent containers are both prevented from performing further updates and are removed by the child container. Further bug fixes with Docker Compose replicas, cross-project stacks, and transitive dependencies are expected to improve reliability when using Watchtower to provide updates in more complex Docker deployments.

Features

• feat: auto-detect container stop timeout from Docker config by @skylenet in #1182
• Add support for file-based notification templates by @nicholas-fedor in #1209
• Update cron package to v3 with enhanced concurrency control and seconds support by @nicholas-fedor in #1208

Bug Fixes

• Fix panic in GetCreateConfig when containerInfo is nil by @nicholas-fedor in #1147
• Resolve self-update container cleanup issues by @nicholas-fedor in #1159
• Lower log level to debug for skipping pinned images by @nicholas-fedor in #1160
• Fix Watchtower depends-on label processing for cross-project Docker Compose dependencies by @nicholas-fedor in #1162
• Fix self-update, container management, and dependency issues by @nicholas-fedor in #1199
• Fix Data Race in Container Concurrent Access by @nicholas-fedor in #1201
• Fix Watchtower self-update logging during safeguard period by @nicholas-fedor in #1204
• Fix transitive dependency restart issue by @nicholas-fedor in #1211

Dependency Updates

• chore(deps): update module github.com/onsi/gomega to v1.39.0 by @renovate[bot] in #1176
• chore(deps): update module golang.org/x/text to v0.33.0 by @renovate[bot] in #1188
• chore(deps): update module github.com/onsi/ginkgo/v2 to v2.27.5 by @renovate[bot] in #1194
• chore(deps): update module github.com/sirupsen/logrus to v1.9.4 by @renovate[bot] in #1203
• chore(deps): update dependency go to v1.25.6 by @renovate[bot] in #1205
• chore(deps): update module github.com/docker/cli to v29.1.5+incompatible by @renovate[bot] in #1212

New Contributors

@skylenet made their first contribution in #1182

Full Changelog

v1.13.1...v1.14.0

Original source Report a problem

Overview

This patch release integrates several bug fixes and improvements. Fixes include false positive mitigations for the new container sorting algorithm's circular reference detection, correcting the no-pull configuration option to correctly monitor the local image cache, and ensuring that setting the notifications level provides the expected level of control over both report and legacy notification verbosity. This release also integrates the latest version of Shoutrrr, which includes subsequent notification fixes.

Improvements include the adding a template entry for the formatting of the self-update cleanup notification message. In addition, the self-update process has been further refined to allow regular, non-Watchtower updates immediately proceeding a self-update, rather than being initially skipped. This should hopefully allow for expected container updates while still preventing Watchtower from spawning orphaned Watchtower containers.

⚠️ As previously mentioned, a rolling-restart container update strategy is not compatible with linked/dependent containers. Watchtower's v1.13 addition of Docker Compose depends-on support now correctly enforces this through the "sanity check" warning. Docker restart policies that ensure Watchtower repeatedly restarts will result in the repeated restarts of Watchtower and subsequent repetition of the warning until the configuration is corrected. ⚠️

Improvements

• Improve punctuation in multiple Watchtower instances log message by @nicholas-fedor in #1136
• Refine Watchtower Self-Update Behavior by @nicholas-fedor in #1137

Bug Fixes

• Fix no-pull mode to enable local image updates by @nicholas-fedor in #1099
• Fix WATCHTOWER_NOTIFICATIONS_LEVEL being ignored in report mode by @nicholas-fedor in #1115
• Fix false positive circular reference detection in dependency sorting by @nicholas-fedor in #1120
• Fix false positive circular reference detection for containers with same service names by @nicholas-fedor in #1139

Notes

This is expected to be the final release for 2025.
As always, if there are bugs, issues, features, etc that you need help with, then please reference either the Issues or Discussions.
Merry Christmas and have a Happy New Year!

Full Changelog: v1.13.0...v1.13.1

Original source Report a problem

Overview

This release introduces Docker Compose depends_on support and implements a fix that ensures proper handling of linked/dependent containers. It also includes bug fixes for self-update handling, notification propagation, HTTP API behavior, and graceful shutdown, along with minor dependency updates.
⚠️

The addition of Docker Compose depends-on support will trigger Watchtower's "Sanity Check" and prevent new and existing users from running Watchtower when they are using the conflicting rolling-restart functionality. (#1106)

Feature Improvements

• Add Docker Compose depends_on support and improve handling of linked/dependent containers by @nicholas-fedor in #1086

Bug Fixes

• Prevent multiple orphaned containers on selfupdate by @nicholas-fedor in #1075
• Fix Notification Propagation for Startup Failures by @nicholas-fedor in #1085
• Fix HTTP API Startup Message Suppression by @nicholas-fedor in #1090
• Enable graceful shutdown with context cancellation by @nicholas-fedor in #1094

Dependency Updates

• Update module github.com/docker/cli to v29.1.3+incompatible by @renovate[bot] in #1083
• Update indirect Go dependencies by @nicholas-fedor in #1088

Full Changelog: v1.12.5...v1.13.0

Original source Report a problem