Missing docs for migration to new builder action

[f18m]

Hi,

I'm a maintainer of a few HA addons/apps.
I've been a long time user of the home-assistant/builder action and now I'm trying to migrate to the new actions.
However I feel like there is no clear migration procedure. I appreciate the README in this project but there are a number of questions related to the migration which are not addressed like:

1. the example pipeline at https://github.com/home-assistant/builder?tab=readme-ov-file#example-workflow only works when you have

on:
  release:
    types: [published]

as trigger. What if I want to publish docker images for un-released content (e.g. I publish a "Beta" version of each addon where I deploy new developments for manual testing across a few HA instances before releasing them in the "main" channel). I think creating a release for "beta" version would be confusing so I'm trying to adapt this pipeline for triggers like on.push . Having an example as part of migration guide would be useful :)

2. with previous home-assistant/builder action, the Dockerfile of the addon/app had to be structured like:

FROM $BUILD_FROM

This does not work anymore apparently; using new action I get:

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 2.39kB done
#1 WARN: InvalidDefaultArgInFrom: Default value for ARG $BUILD_FROM results in empty or invalid base image name (line 41)
#1 DONE 0.1s

 1 warning found (use docker --debug to expand):
 - InvalidDefaultArgInFrom: Default value for ARG $BUILD_FROM results in empty or invalid base image name (line 41)
Dockerfile:41
--------------------
  39 |     # --- Actual ADDON layer
  40 |     
  41 | >>> FROM $BUILD_FROM
  42 |     
  43 |     # Add env
--------------------
ERROR: failed to build: failed to solve: base name ($BUILD_FROM) should not be blank

Also the docs at https://developers.home-assistant.io/docs/apps/tutorial#the-dockerfile-file are not updated and still reference the $BUILD_FROM bit...
what's the new intended base layer for HA addons?

Thanks a lot!

[eshattow]

Have a look at uses: home-assistant/builder/actions/... in https://github.com/home-assistant/docker-base/blob/master/.github/workflows/build-base-image.yml and the associated Docker files. I hope that is helpful although I don't know the answer to your question directly. Also please contribute pull request(s) if you learn a better way to do this the HomeAssistant team does accept outside contributions, depending on whether they are scoped within the project policies and such.

[f18m]

thanks @eshattow .
Regarding my own question #2 above, I found for new App build process probably the :

FROM ghcr.io/home-assistant/base:3.23

is the intended solution.
I would open PRs but I first would like to hear from the maintainers where they think this type of documentation should go... e.g. in main README of this builder project?

[agners]

@f18m there is a blog post about the migration on our developer website: Migrating app builds to Docker BuildKit. We probably should add a link from here 😅

The trigger should also work with on push. Can you still reproduce that?

[eshattow]

Maybe some generated documentation from the actions.yml each? i.e. it's much more understandable than the yaml format itself to instead read:

inputs to home-assistant/builder/actions/cosign-verify/action.yml:

image: Container image reference to verify
cosign-identity: Certificate identity regexp for verifying cache images (defaults to current repo pattern)
cosign-issuer: Certificate OIDC issuer regexp for all cosign verification
allow-failure: Whether to allow failure of this step (defaults to false). Only shows a warning if verification fails.

inputs to home-assistant/builder/actions/build-image/action.yml:

arch: Architecture to build (e.g., "amd64")
build-args: Additional build arguments (key=value format, one per line)
cache-gha: Whether to use GitHub Actions cache for build caching
cache-gha-scope: Scope for build cache sharing (defaults to architecture, set if building multiple images from a single repo)
cache-image-tag: Tag of the image containing BuildKit inline cache metadata
container-registry-password: Password for container registry (use secrets.GITHUB_TOKEN for GHCR)
container-registry: Container registry (e.g., "ghcr.io")
container-registry-username: Username for container registry (defaults to repository owner)
context: Build context path (usually the directory with Dockerfile, defaults to repository root)
cosign: Whether to sign images with Cosign
cosign-base-identity: Certificate identity regexp for verifying the base (FROM) image
cosign-base-issuer: Certificate OIDC issuer regexp for base image verification (defaults to cosign-issuer)
cosign-base-verify: Base image reference to verify with cosign before building
cosign-identity: Certificate identity regexp for verifying cache images (defaults to current repo pattern)
cosign-issuer: Certificate OIDC issuer regexp for all cosign verification
file: Dockerfile path (defaults to "Dockerfile" in the context directory)
image: Full image name without tag (e.g., "ghcr.io/home-assistant/amd64-base")
image-tags: Image tags, one per line
labels: Additional OCI labels (key=value format, one per line)
load: Whether to load the built image into the Docker engine
push: Whether to push images to registry
version: Image version label

inputs to home-assistant/builder/actions/prepare-multi-arch-matrix/action.yml:

architectures: Architectures to build (JSON array, e.g., '["amd64", "aarch64", "riscv64"]')
image-name: Image name without a tag (e.g., "base-python")
registry-prefix: Registry and namespace prefix (e.g., "ghcr.io/owner") ; default is ghcr.io/${{ github.repository_owner }}

inputs to home-assistant/builder/actions/publish-multi-arch-manifest/action.yml:

architectures: Architectures (JSON array, e.g., '["amd64", "aarch64"]')
container-registry: Container registry (e.g., "ghcr.io")
container-registry-password: Password for container registry (use secrets.GITHUB_TOKEN for GHCR)
container-registry-username: Username for container registry (defaults to repository owner)
cosign: Whether to sign the manifest with Cosign
image-name: Image name without a tag (e.g., "base-python")
image-tags: Image tags, one per line (first tag is the primary tag used for per-arch image lookup)
registry-prefix: Registry and namespace prefix (e.g., "ghcr.io/owner") ; default is ghcr.io/${{ github.repository_owner }}

builder/main.py possible command arguments:

--apk APKs they are needed to build this.
--pip PiPy modules needed to build this.
--index Index URL of remote wheels repository.
--skip-binary List of packages to skip wheels from pypi.
--requirement Python requirement file.
--requirement-diff Python requirement file to calc the different for selective builds.
--constraint Python constraint file.
--prebuild-dir Folder which includes already built wheels for upload.
--single Install every package as single requirement.
--local Build wheel from local folder setup.
--test Test building wheels, no upload.
--remote Remote URL pass to upload plugin.
--timeout Max runtime for pip before abort.
The above options appear to be built up as an environment variable specified in the workflow for {org}/wheels action.yml after the SSH key import step and the docker pull of the wheels docker container. The use of "/opt/wheels" in the upload path is hard-coded there. Later those built options are used in the "Create container" shell snippet that follows, where '--index' then additionally tracks ${{ inputs.wheels-index }}.
The "musllinux-index" directory name is built from _MUSLLINUX const in builder/infra.py expanded by builder/pip.py:create_wheels_index() to f"{base_index}/{_MUSLLINUX}-index/". The "musllinux" directory name is built from _MUSLLINUX const in builder/infra.py expanded by builder/pip.py:create_wheels_list() to f"{base_index}/{_MUSLLINUX}/". The {index} is passed to builder/pip.py from as a click command argument "--index"

Pair a generated one-page reference with some usage notes with examples, so the examples will not suffer maintenance burden to be updated with the actions.yml content.

[f18m]

@agners ,
thanks for the link to the blog post.
And for the question about the push trigger... indeed I just checked and the workflow works. I expected github.event.release.tag_name to fail on push triggers but it looks like they simple expand to nothing. So the workflow works.

I opened a PR at #304 with these trivial improvements to the README of this project...