Skip to content

How to keep pinned versions in a Dockerfile fresh

If your Dockerfile pins a tool version in a build argument, renovatebot can keep that version fresh and auto-open Merge Requests when a new release is available. This is the counterpart to keeping docker image references fresh. That guide tracks a full image reference (name and tag) in a Terraform configuration. This one tracks a dependency pinned inside the Dockerfile. For background on how renovatebot fits into our workflow, see the renovatebot explanation.

Prerequisites

  • Renovatebot is already running on your project. If not, first start using renovatebot.
  • A Dockerfile that pins a version in an ARG or ENV variable whose name ends in _VERSION.

Enable the customManagers:dockerfileVersions preset

Renovate ships a preset that finds these dependencies for you. It matches files named like a Dockerfile and reads a # renovate: comment to learn the datasource and package name.

Add the preset to the extends array in renovate.json:

renovate.json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "local>uis/devops/renovate-config",
    "customManagers:dockerfileVersions"
  ]
}

Annotate the dependency in your Dockerfile

Add a # renovate: comment on the line immediately above the pinned variable. The comment tells renovate where to look up new versions. Two things must hold for the preset to pick this up. The variable name has to end in _VERSION, and the # renovate: comment has to sit on the immediately preceding line. The datasource and depName values come from the Renovate datasource reference.

Info

The following two sections are simply examples of what is possible with this preset. Most Renovate datasources can be used the same way — pick whichever one matches how you're fetching the dependency (e.g. npm, docker, github-tags, pypi).

Download an architecture-specific release binary

When you fetch a prebuilt binary, use the github-releases datasource together with Docker's built-in TARGETARCH argument so the same Dockerfile works on every architecture.

Dockerfile
# TARGETARCH is set automatically by BuildKit, e.g. amd64 or arm64.
ARG TARGETARCH

# renovate: datasource=github-releases depName=mikefarah/yq
ARG YQ_VERSION=4.44.6
RUN curl -fsSL -o /usr/local/bin/yq \
    "https://github.com/mikefarah/yq/releases/download/v${YQ_VERSION}/yq_linux_${TARGETARCH}" \
    && chmod +x /usr/local/bin/yq

TARGETARCH is one of the platform build arguments that BuildKit sets for you. Declare it with a bare ARG TARGETARCH before you use it. Renovate only tracks the version, so the download URL stays multi-arch.

Pin an apt-get package

When you install a Debian package at a pinned version, use the deb datasource. You do not need TARGETARCH here. Debian version strings are the same across architectures, so the pinned version resolves on every arch.

Dockerfile
# renovate: datasource=deb depName=curl versioning=deb registryUrl=https://deb.debian.org/debian?suite=trixie&components=main&binaryArch=amd64
ARG CURL_VERSION=8.14.1-2+deb13u4
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl="${CURL_VERSION}" \
    && rm -rf /var/lib/apt/lists/*

The registryUrl needs the suite, components, and binaryArch query parameters so renovate knows which package index to query. The binaryArch only affects that lookup, not the built image.

Renovatebot will now open Merge Requests to bump this version when a new release is published.

Important

This preset only updates versions pinned in build arguments and environment variables. It does not touch the base image on your FROM line. That is kept current by the shared local>uis/devops/renovate-config preset already. Before you commit, it is worth running renovatebot locally to confirm the dependency is detected, and adding pre-commit hooks to validate your configuration.

Summary

In this guide you enabled the customManagers:dockerfileVersions preset and annotated a pinned version in your Dockerfile so renovatebot keeps it fresh.

Next steps