[libcxx-commits] [libcxx] [llvm] [libc++] Simplify the workflow for updating CI docker images (PR #186456)

[Louis Dionne via libcxx-commits]

https://github.com/ldionne created https://github.com/llvm/llvm-project/pull/186456

This allows updating the Docker images (both base and derived) in a single PR instead of having to do two commits.

Fixes #186438

>From 4aadf14ce874622774e59426288278f33e36478e Mon Sep 17 00:00:00 2001
From: Louis Dionne <ldionne.2 at gmail.com>
Date: Fri, 13 Mar 2026 13:02:31 -0400
Subject: [PATCH] [libc++] Simplify the workflow for updating CI docker images

This allows updating the Docker images (both base and derived) in a
single PR instead of having to do two commits.

Fixes #186438
---
 .github/workflows/libcxx-build-containers.yml |  2 ++
 libcxx/docs/Contributing.rst                  | 27 ++++++++++++-------
 libcxx/utils/ci/docker/docker-compose.yml     |  6 ++---
 3 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/libcxx-build-containers.yml b/.github/workflows/libcxx-build-containers.yml
index e73f15e87a7a7..2c8a7f1267775 100644
--- a/.github/workflows/libcxx-build-containers.yml
+++ b/.github/workflows/libcxx-build-containers.yml
@@ -49,11 +49,13 @@ jobs:
       run: docker compose --file libcxx/utils/ci/docker/docker-compose.yml build libcxx-linux-builder
       env:
         TAG: ${{ github.sha }}
+        BASE_IMAGE_VERSION: ${{ github.sha }}
 
     - name: Build the Android builder image
       run: docker compose --file libcxx/utils/ci/docker/docker-compose.yml build libcxx-android-builder
       env:
         TAG: ${{ github.sha }}
+        BASE_IMAGE_VERSION: ${{ github.sha }}
 
     - name: Log in to GitHub Container Registry
       uses: docker/login-action at 5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst
index 465bf9d0542c8..d269b9cb28cf6 100644
--- a/libcxx/docs/Contributing.rst
+++ b/libcxx/docs/Contributing.rst
@@ -285,15 +285,24 @@ files is read by the `Terraform configuration in llvm-zorg
 When updating the container image, you can either update just the runner binary (the part
 that connects to Github), or you can update everything (tools, etc.). To update the runner
 binary, bump the value of ``GITHUB_RUNNER_VERSION`` in ``libcxx/utils/ci/docker/docker-compose.yml``.
-To update all of the tools, bump ``BASE_IMAGE_VERSION`` to a newer version of the ``libcxx-linux-builder-base``
-image. You can see all versions of that image at https://github.com/llvm/llvm-project/pkgs/container/libcxx-linux-builder-base.
-
-On push to ``main``, a new version of both the ``libcxx-linux-builder`` and the ``libcxx-android-builder``
-images will be built and pushed to https://github.com/llvm/llvm-project/packages.
-
-You can then update the image used by the actual runners by changing the image encoded in
-``libcxx/utils/ci/images`` and asking an LLVM premerge maintainer (a Google employee) to
-actually deploy the changes to the GKE cluster via Terraform.
+To update the base tools (compilers, system packages, etc.), modify ``linux-builder-base.dockerfile``
+directly.
+
+On push to ``main``, new versions of ``libcxx-linux-builder-base``, ``libcxx-linux-builder``,
+and ``libcxx-android-builder`` are built in a workflow run and tagged with a commit SHA (the
+current ``HEAD``). The derived images (``libcxx-linux-builder`` and ``libcxx-android-builder``)
+are automatically wired to use the base image built in that same workflow run. All images are
+pushed to https://github.com/llvm/llvm-project/packages.
+
+To update the runners to use a new image, the workflow is:
+
+1. Make dockerfile changes (base or derived) in a PR, land it, and wait for the
+   ``Build Docker images for libc++ CI`` workflow to complete on ``main``. Note
+   the resulting commit SHA.
+2. Update ``libcxx/utils/ci/images/libcxx_next_runners.txt`` (or the appropriate runners
+   file) with that SHA.
+3. Ask an LLVM premerge maintainer (a Google employee) to apply the changes to the
+   GKE cluster via Terraform.
 
 Monitoring premerge testing performance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/libcxx/utils/ci/docker/docker-compose.yml b/libcxx/utils/ci/docker/docker-compose.yml
index 1a1fb84c8bb79..8fa9394cc091a 100644
--- a/libcxx/utils/ci/docker/docker-compose.yml
+++ b/libcxx/utils/ci/docker/docker-compose.yml
@@ -4,7 +4,7 @@
 #
 # Images can be built with:
 #
-#   $ docker compose --file libcxx/utils/ci/docker/docker-compose.yml build <image-name>
+#   $ BASE_IMAGE_VERSION=<sha> docker compose --file libcxx/utils/ci/docker/docker-compose.yml build <IMAGE>
 #
 
 services:
@@ -23,7 +23,7 @@ services:
       context: ../../../.. # monorepo root
       dockerfile: libcxx/utils/ci/docker/linux-builder.dockerfile
       args:
-        BASE_IMAGE_VERSION: 825943e06f840710177e5514c4f61c9e73660c44
+        BASE_IMAGE_VERSION: ${BASE_IMAGE_VERSION:?BASE_IMAGE_VERSION must be set to a libcxx-linux-builder-base image SHA}
         GITHUB_RUNNER_VERSION: 2.331.0
 
   libcxx-android-builder:
@@ -32,7 +32,7 @@ services:
       context: ../../../.. # monorepo root
       dockerfile: libcxx/utils/ci/docker/android-builder.dockerfile
       args:
-        BASE_IMAGE_VERSION: 825943e06f840710177e5514c4f61c9e73660c44
+        BASE_IMAGE_VERSION: ${BASE_IMAGE_VERSION:?BASE_IMAGE_VERSION must be set to a libcxx-linux-builder-base image SHA}
         ANDROID_CLANG_VERSION: r563880
         ANDROID_CLANG_PREBUILTS_COMMIT: 6ae4184bb8706f9731569b9a0a82be3fcdcb951c
         ANDROID_SYSROOT_COMMIT: f8b85cc5262c6e5cbc9a92c1bab2b18b32a4c63f