Merge pull request #2259 from larsewi/build-base-images-debian-13

Add debian-13 to build-base-images workflow matrix

Author: larsewi

.github/workflows/build-base-images.yml

@@ -19,6 +19,7 @@ jobs:
           - ubuntu-24
           - debian-11
           - debian-12
+          - debian-13
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6

build-in-container.md

@@ -42,18 +42,19 @@ None of the above arguments are required for `--update`.
 
 ### Optional arguments
 
-| Option             | Default                          | Description                                                         |
-| ------------------ | -------------------------------- | ------------------------------------------------------------------- |
-| `--output-dir`     | `./output`                       | Where to write output packages                                      |
-| `--cache-dir`      | `~/.cache/cfengine/buildscripts` | Dependency cache directory                                          |
-| `--build-number`   | `1`                              | Build number for package versioning                                 |
-| `--version`        | auto                             | Override version string                                             |
-| `--rebuild-image`  |                                  | Force rebuild of Docker image (bypasses Docker layer cache)         |
-| `--push-image`     |                                  | Build image and push to registry, then exit                         |
-| `--update`         |                                  | Fetch latest image versions from registry and update platforms.json |
-| `--shell`          |                                  | Drop into a bash shell inside the container for debugging           |
-| `--list-platforms` |                                  | List available platforms and exit                                   |
-| `--source-dir`     | parent of `buildscripts/`        | Root directory containing repos                                     |
+| Option             | Default                          | Description                                                                        |
+| ------------------ | -------------------------------- | ---------------------------------------------------------------------------------- |
+| `--output-dir`     | `./output`                       | Where to write output packages                                                     |
+| `--cache-dir`      | `~/.cache/cfengine/buildscripts` | Dependency cache directory                                                         |
+| `--build-number`   | `1`                              | Build number for package versioning                                                |
+| `--version`        | auto                             | Override version string                                                            |
+| `--rebuild-image`  |                                  | Force rebuild of Docker image (bypasses Docker layer cache)                        |
+| `--push-image`     |                                  | Build image and push to registry, then exit                                        |
+| `--update`         |                                  | Fetch latest image versions from registry and update platforms.json                |
+| `--update-sha`     |                                  | Fetch latest base image manifest digests from Docker Hub and update platforms.json |
+| `--shell`          |                                  | Drop into a bash shell inside the container for debugging                          |
+| `--list-platforms` |                                  | List available platforms and exit                                                  |
+| `--source-dir`     | parent of `buildscripts/`        | Root directory containing repos                                                    |
 
 ## Supported platforms
 
@@ -64,8 +65,26 @@ None of the above arguments are required for `--update`.
 | `ubuntu-24` | `ubuntu:24.04` |
 | `debian-11` | `debian:11`    |
 | `debian-12` | `debian:12`    |
+| `debian-13` | `debian:13`    |
+
+Adding a new Debian/Ubuntu platform requires a new entry in `platforms.json`
+and adding the platform name to the matrix in
+`.github/workflows/build-base-images.yml` so the weekly job builds and
+pushes its image to `ghcr.io`. Without the matrix entry, no image is ever
+pushed and the `update-base-images.yml` workflow will fail with a 403 from
+`ghcr.io` when it queries tags for the missing repository.
+
+The new entry in `platforms.json` needs:
+
+- `image_version`: set to `"latest"` as a placeholder. The
+  `update-base-images.yml` workflow (or `./build-in-container.py --update`
+  run locally) will replace it with the real ghcr.io tag after the first
+  image is pushed.
+- `base_image_sha`: the Docker Hub manifest digest for the `base_image`.
+  Don't copy this by hand — run `./build-in-container.py --update-sha
+--platform <new-platform>` and it will fetch the current digest from
+  Docker Hub and write it into `platforms.json`.
 
-Adding a new Debian/Ubuntu platform requires only a new entry in `platforms.json`.
 Adding a non-debian based platform (e.g.,
 RHEL/CentOS) requires a new `container/Dockerfile.rhel` plus platform entries.
 
@@ -151,6 +170,20 @@ The `update-base-images.yml` workflow automates this step. It runs weekly
 `platforms.json` changes. This workflow requires `contents: write` and
 `pull-requests: write` permissions.
 
+The `base_image_sha` digests in `platforms.json` pin each platform to a
+specific Docker Hub manifest. To refresh them to the current digests:
+
+```bash
+# Update all platforms
+./build-in-container.py --update-sha
+
+# Update a single platform
+./build-in-container.py --update-sha --platform ubuntu-22
+```
+
+The `update-base-image-shas.yml` workflow automates this. It runs weekly
+(Monday at 01:00 UTC) and opens a pull request with any digest changes.
+
 The workflow authenticates to `ghcr.io` using the automatic `GITHUB_TOKEN`
 provided by GitHub Actions. For this to work: