Skip to content

build: GitHub Builder runner mappings #25086

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
crazy-max merged 1 commit into from
May 18, 2026
Merged

build: GitHub Builder runner mappings #25086

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 45 additions & 5 deletions content/manuals/build/ci/github-actions/github-builder/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Copy link
Copy Markdown
Member

@thaJeztah thaJeztah May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a page we could link to in the GitHub docs that shows the available labels?

Copy link
Copy Markdown
Member Author

@crazy-max crazy-max May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes there is https://docs.github.com/en/actions/reference/runners/github-hosted-runners#supported-runners-and-hardware-resources and https://github.com/actions/partner-runner-images/#available-images but not sure about linking to these pages though 🤔

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
Comment thread
crazy-max marked this conversation as resolved.
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)
Expand Down
5 changes: 4 additions & 1 deletion content/manuals/build/ci/github-actions/github-builder/bake.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 7 additions & 5 deletions content/manuals/build/ci/github-actions/github-builder/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
11 changes: 7 additions & 4 deletions content/manuals/build/ci/github-actions/multi-platform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down