From e79ee7eb5e2ff6ea0c177726eca20fdd6dc7c0f0 Mon Sep 17 00:00:00 2001 From: CrazyMax <1951866+crazy-max@users.noreply.github.com> Date: Mon, 18 May 2026 12:01:09 +0200 Subject: [PATCH] build: GitHub Builder runner mappings Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- .../github-builder/architecture.md | 50 +++++++++++++++++-- .../ci/github-actions/github-builder/bake.md | 5 +- .../ci/github-actions/github-builder/build.md | 12 +++-- .../build/ci/github-actions/multi-platform.md | 11 ++-- 4 files changed, 63 insertions(+), 15 deletions(-) diff --git a/content/manuals/build/ci/github-actions/github-builder/architecture.md b/content/manuals/build/ci/github-actions/github-builder/architecture.md index 0c0db641a90e..bcb3bddda746 100644 --- a/content/manuals/build/ci/github-actions/github-builder/architecture.md +++ b/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) diff --git a/content/manuals/build/ci/github-actions/github-builder/bake.md b/content/manuals/build/ci/github-actions/github-builder/bake.md index 6934baec8c93..c40d4a6314c4 100644 --- a/content/manuals/build/ci/github-actions/github-builder/bake.md +++ b/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 diff --git a/content/manuals/build/ci/github-actions/github-builder/build.md b/content/manuals/build/ci/github-actions/github-builder/build.md index 202739fb58c8..46f15d37ee21 100644 --- a/content/manuals/build/ci/github-actions/github-builder/build.md +++ b/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 diff --git a/content/manuals/build/ci/github-actions/multi-platform.md b/content/manuals/build/ci/github-actions/multi-platform.md index cc64d1803490..1b03149a1257 100644 --- a/content/manuals/build/ci/github-actions/multi-platform.md +++ b/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