Merge pull request #25086 from crazy-max/github-builder-runner

build: GitHub Builder runner mappings

Author: crazy-max

content/manuals/build/ci/github-actions/github-builder/architecture.md

@@ -27,11 +27,11 @@ conditions, permissions, secrets, target selection, metadata inputs, and the
 choice between image output and local output.
 
 Inside the reusable workflow, the first phase prepares the build. It validates
-the incoming inputs, resolves the appropriate runner, and expands a
-multi-platform request into one job per platform. The execution model is
-easiest to picture as a matrix where `linux/amd64` runs on `ubuntu-24.04` and
-`linux/arm64` runs on `ubuntu-24.04-arm`. Each platform job builds independently,
-then the workflow finalizes the result into one caller-facing output contract.
+the incoming inputs, resolves the runner config, and expands a multi-platform
+request into one job per platform. The execution model is easiest to picture as
+a matrix where `linux/amd64` runs on `ubuntu-24.04` and `linux/arm64` runs on
+`ubuntu-24.04-arm`. Each platform job builds independently, then the workflow
+finalizes the result into one caller-facing output contract.
 
 ```yaml
 requested platforms:
@@ -42,6 +42,46 @@ conceptual platform jobs:
   linux/arm64 -> ubuntu-24.04-arm
 ```
 
+### Runner selection
+
+The `runner` input accepts either a single GitHub-hosted Linux runner label or a
+newline-delimited platform mapping.
+
+The default value is a platform mapping that uses GitHub-hosted Ubuntu runners:
+
+```yaml
+runner: |
+  default=ubuntu-24.04
+  linux/arm=ubuntu-24.04-arm
+  linux/arm64=ubuntu-24.04-arm
+```
+
+In the platform job, the runner label resolves to a single value:
+
+```yaml
+runner: ubuntu-24.04
+```
+
+A mapping must define a `default` runner. Other keys are platform prefixes, and
+the most specific matching prefix wins. For example, `linux/arm` matches
+variants such as `linux/arm/v7`, while `linux/arm64` is a separate prefix:
+
+In the following example, `linux` matches Linux platforms that do not match a
+longer prefix. The `default` key is still required because it is the fallback
+when no platform prefix matches.
+
+```yaml
+runner: |
+  default=ubuntu-24.04
+  linux=ubuntu-24.04
+  linux/arm=ubuntu-24.04-arm
+  linux/arm64=ubuntu-24.04-arm
+```
+
+The reusable workflows require GitHub-hosted Linux runners. The legacy `auto`,
+`amd64`, and `arm64` values are still accepted for compatibility, but emit
+deprecation warnings. Use an explicit runner label or platform mapping instead.
+
 ## Execution path
 
 ![GitHub Builder execution flow](./images/execution-flow.png)

content/manuals/build/ci/github-actions/github-builder/bake.md

@@ -58,7 +58,10 @@ builds aren't supported because [SLSA provenance](../attestations.md), digest
 handling, and manifest creation are scoped to a single target.
 
 The workflow validates the definition before the build starts and resolves
-the target from the files you pass in `files`.
+the target from the files you pass in `files`. Runner selection uses the same
+`runner` input as the Build workflow. Set a single GitHub-hosted Linux runner
+label or a platform mapping when the default mapping is not enough. For details,
+see [runner selection](architecture.md#runner-selection).
 
 ## Override target values and variables
 

content/manuals/build/ci/github-actions/github-builder/build.md

@@ -55,11 +55,13 @@ jobs:
 
 When you set `output: image`, `meta-images` is required because the workflow
 creates image names and [manifest tags](../manage-tags-labels.md) from that
-input. `runner: auto` and `distribute: true` are the defaults, so a
-multi-platform build can fan out across native GitHub-hosted runners instead
-of forcing the whole build onto one machine. `sign: auto` is also the default,
-which means the workflow signs [attestation manifests](../attestations.md)
-when the image is pushed.
+input. `distribute: true` is the default, so a multi-platform build can fan out
+across native GitHub-hosted runners instead of forcing the whole build onto one
+machine. The default `runner` mapping sends Linux Arm platforms to
+`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To change that
+mapping, see [runner selection](architecture.md#runner-selection). `sign: auto`
+is also the default, which means the workflow signs
+[attestation manifests](../attestations.md) when the image is pushed.
 
 ## Export local output as an artifact
 

content/manuals/build/ci/github-actions/multi-platform.md

@@ -140,10 +140,13 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 ```
 
-With `runner: auto` and `distribute: true`, which are the defaults, the
-workflow splits the build into one platform per runner and assembles the final
-multi-platform image in its finalize phase. If you need to control the Docker
-build inputs directly, see [Build with Docker GitHub Builder build.yml](github-builder/build.md).
+With `distribute: true`, which is the default, the workflow splits the build
+into one platform per runner and assembles the final multi-platform image in
+its finalize phase. The default `runner` mapping sends Linux Arm platforms to
+`ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To customize
+the mapping, see [runner selection](github-builder/architecture.md#runner-selection).
+If you need to control the Docker build inputs directly, see
+[Build with Docker GitHub Builder build.yml](github-builder/build.md).
 
 ### With Bake