Update image build instructions after Builder deprecation, add blog post#3027
Merged
Update image build instructions after Builder deprecation, add blog post#3027
Conversation
Document the recent changes in how apps and other HA containers are built and update docs where they were deprecated (e.g. still mentioning Codenotary). Add blog post describing the changes in bigger picture and link it from the old 2020 post that described how the builder action can be used. Closes #3001, closes #178, closes #803, closes #1939, closes #2026
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded a builder migration guide and updated docs to migrate CI/local image builds from the legacy Changes
Sequence Diagram(s)sequenceDiagram
actor Developer
participant Repo as "GitHub Repository"
participant GH_Actions as "GitHub Actions"
participant Composite as "HA Composite Actions"
participant BuildKit as "Docker BuildKit"
participant Registry as "Container Registry (GHCR)"
Developer->>Repo: Push code + Dockerfile
Repo->>GH_Actions: Trigger workflow
GH_Actions->>Composite: Invoke build/publish composite actions
Composite->>BuildKit: Run docker build --platform (BuildKit)
BuildKit->>BuildKit: Build per-arch images
BuildKit->>Registry: Push per-arch images
Composite->>Registry: Publish multi-arch manifest
Registry->>Developer: Multi-arch image available (ghcr.io/...)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/apps/configuration.md (1)
120-120: Rephrase for grammar clarity.Line 120 reads awkwardly: “does recursively search”. Use “searches recursively” for concise, natural phrasing.
As per coding guidelines, "Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness."Suggested fix
-Avoid using `config.yaml` as filename in your app for anything other than the app configuration. The Supervisor does recursively search for `config.yaml` in the app repository. +Avoid using `config.yaml` as filename in your app for anything other than the app configuration. The Supervisor searches recursively for `config.yaml` in the app repository.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/apps/configuration.md` at line 120, Edit the sentence that currently reads "does recursively search" concerning how the Supervisor handles config.yaml and change it to the grammatically correct "searches recursively" (refer to the phrase "config.yaml" and the existing fragment "does recursively search") so the line becomes concise and natural per Microsoft Style Guide.blog/2026-04-02-builder-migration.md (1)
8-8: Tighten the opening instruction for a more direct tone.Line 8 is understandable, but a direct imperative reads cleaner in instructional docs.
As per coding guidelines, "For instructional content in documentation, use a direct and authoritative tone."Suggested wording
-The legacy `home-assistant/builder` container and the old `home-assistant/builder` GitHub Action have been retired. We recommend to migrate all app (formerly add-on) repositories to allow direct build with Docker BuildKit and to use the new composite actions described in this post. +The legacy `home-assistant/builder` container and GitHub Action have been retired. Migrate app (formerly add-on) repositories to direct Docker BuildKit builds and use the composite actions described in this post.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@blog/2026-04-02-builder-migration.md` at line 8, Rewrite the sentence about retiring the legacy `home-assistant/builder` container and GitHub Action into a direct imperative: instruct readers to "Migrate your app repositories to build directly with Docker BuildKit and use the new composite actions" and retain the clarifying parenthetical "(formerly add-on)". Update the line referencing `home-assistant/builder` and "Docker BuildKit" and "composite actions" so it reads as a clear command rather than a passive statement.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/apps/configuration.md`:
- Around line 80-82: Replace the container label value for io.hass.type from
"app" to "addon" in the configuration snippet so it matches the migration guide
and Supervisor requirements; locate the code block containing the labels (the
line with io.hass.type="app" next to io.hass.arch="aarch64|amd64") and change it
to io.hass.type="addon" while keeping the surrounding label format intact.
In `@docs/apps/publishing.md`:
- Around line 7-13: The two headings "Pre-built containers" and "Locally built
containers" are using H3 (###) and should be promoted to H2 (##) to fix the
heading level jump; update both heading lines in the docs to use H2 syntax so
the document outline is consistent and MD001 warnings are resolved.
---
Nitpick comments:
In `@blog/2026-04-02-builder-migration.md`:
- Line 8: Rewrite the sentence about retiring the legacy
`home-assistant/builder` container and GitHub Action into a direct imperative:
instruct readers to "Migrate your app repositories to build directly with Docker
BuildKit and use the new composite actions" and retain the clarifying
parenthetical "(formerly add-on)". Update the line referencing
`home-assistant/builder` and "Docker BuildKit" and "composite actions" so it
reads as a clear command rather than a passive statement.
In `@docs/apps/configuration.md`:
- Line 120: Edit the sentence that currently reads "does recursively search"
concerning how the Supervisor handles config.yaml and change it to the
grammatically correct "searches recursively" (refer to the phrase "config.yaml"
and the existing fragment "does recursively search") so the line becomes concise
and natural per Microsoft Style Guide.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f1505215-ba83-4f68-a729-15187f072acd
📒 Files selected for processing (8)
blog/2020-10-29-supervisor-update.mdblog/2026-04-02-builder-migration.mddocs/apps.mddocs/apps/configuration.mddocs/apps/publishing.mddocs/apps/security.mddocs/apps/testing.mddocs/supervisor/development.md
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/apps/publishing.md (1)
21-22: Minor grammar improvement.The phrase "can be then used" would read more naturally as "can then be used."
✍️ Suggested wording improvement
-The recommended way to build and publish multi-architecture app images is through GitHub Actions using the builder composite actions maintained by the Home Assistant project. These actions can be then used for a matrix of builds in an app repository. See the [builder workflow](https://github.com/home-assistant/apps-example/blob/main/.github/workflows/builder.yaml) in the example app repository for a complex example of building multiple apps, or the [example workflow](https://github.com/home-assistant/builder?tab=readme-ov-file#example-workflow) in the builder repository for a single app build. The builder actions are designed to be flexible and can be used in more complex workflows as needed. +The recommended way to build and publish multi-architecture app images is through GitHub Actions using the builder composite actions maintained by the Home Assistant project. These actions can then be used for a matrix of builds in an app repository. See the [builder workflow](https://github.com/home-assistant/apps-example/blob/main/.github/workflows/builder.yaml) in the example app repository for a complex example of building multiple apps, or the [example workflow](https://github.com/home-assistant/builder?tab=readme-ov-file#example-workflow) in the builder repository for a single app build. The builder actions are designed to be flexible and can be used in more complex workflows as needed.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/apps/publishing.md` around lines 21 - 22, Update the sentence that currently reads "These actions can be then used for a matrix of builds in an app repository." to use the improved phrasing "These actions can then be used for a matrix of builds in an app repository." — locate the phrase "can be then used" in the paragraph referencing the builder workflow and replace it with "can then be used".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/apps/publishing.md`:
- Around line 21-22: Update the sentence that currently reads "These actions can
be then used for a matrix of builds in an app repository." to use the improved
phrasing "These actions can then be used for a matrix of builds in an app
repository." — locate the phrase "can be then used" in the paragraph referencing
the builder workflow and replace it with "can then be used".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b3b3d745-efb9-410e-a3ef-6e170393a7b5
📒 Files selected for processing (1)
docs/apps/publishing.md
agners
requested changes
Apr 1, 2026
Member
agners
left a comment
agners
left a comment
There was a problem hiding this comment.
Nice, some much needed love for some of the pages 😅 .
I wonder if we should mention that we expect a Unix/Linux type environment, e.g. advice users to use WSL2 on Windows 🤔 .
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Co-authored-by: Stefan Agner <[email protected]> Co-authored-by: Jan Čermák <[email protected]>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/supervisor/development.md (1)
31-37: Usingdocker buildx buildis clearer butdocker build --pushworks on modern Docker.The
--pushflag is natively supported by modern Docker (which uses Buildx by default), so the existingdocker build --pushcommand will work for most users. However, explicitly usingdocker buildx buildmakes the builder choice clear and is more reliable for older setups where DOCKER_BUILDKIT might be disabled. If clarity is desired, this change is optional.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/supervisor/development.md` around lines 31 - 37, Replace the docker build invocation shown (the block containing "--platform linux/arm64 --tag ghcr.io/YOUR_GH_USERNAME/aarch64-hassio-supervisor:latest --push .") with an explicit buildx call by using "docker buildx build" instead of "docker build" so the builder is explicit and the --push behavior is reliable across environments; keep the existing flags (--platform, --tag, --push, .) unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/supervisor/development.md`:
- Line 64: Replace the current personal-account visibility link
(https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#configuring-visibility-of-packages-for-your-personal-account)
in the sentence about GHCR image visibility with the organization-specific
package visibility docs URL so the guidance applies to org namespaces as well;
locate the sentence that begins "Docker images uploaded to GHCR are by default
private..." and update the link to the org visibility documentation (or include
both personal and org links) to avoid confusion.
---
Nitpick comments:
In `@docs/supervisor/development.md`:
- Around line 31-37: Replace the docker build invocation shown (the block
containing "--platform linux/arm64 --tag
ghcr.io/YOUR_GH_USERNAME/aarch64-hassio-supervisor:latest --push .") with an
explicit buildx call by using "docker buildx build" instead of "docker build" so
the builder is explicit and the --push behavior is reliable across environments;
keep the existing flags (--platform, --tag, --push, .) unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 17b484b0-204b-4ea5-b488-9b0a420c7b67
📒 Files selected for processing (2)
blog/2026-04-02-builder-migration.mddocs/supervisor/development.md
✅ Files skipped from review due to trivial changes (1)
- blog/2026-04-02-builder-migration.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/apps/presentation.md (1)
220-220:⚠️ Potential issue | 🟠 MajorRemove obsolete CodeNotary security-point guidance
Line 220 still documents a security score bonus for CodeNotary CAS, which conflicts with the PR objective to remove obsolete/not-available notarization guidance (
#2026). Please remove or replace this row with current notarization guidance.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/apps/presentation.md` at line 220, Remove the obsolete markdown table row that grants "+1" for CodeNotary CAS (the line containing "| App is signed with [CodeNotary](https://cas.codenotary.com/)| +1||") and either delete the row entirely or replace it with up-to-date notarization guidance and the correct scoring/columns; ensure any references to the CodeNotary bonus elsewhere in the document are updated or removed so the table and narrative remain consistent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/apps/configuration.md`:
- Line 131: The markdown table row for the `arch` entry is missing a trailing
pipe causing MD055 warnings; fix by adding the missing trailing `|` at the end
of the `| `arch` | list | A list of supported architectures: `aarch64`, `amd64`.
|` row and likewise add a trailing `|` to the other affected row around line 172
so all table rows consistently start and end with `|`.
---
Outside diff comments:
In `@docs/apps/presentation.md`:
- Line 220: Remove the obsolete markdown table row that grants "+1" for
CodeNotary CAS (the line containing "| App is signed with
[CodeNotary](https://cas.codenotary.com/)| +1||") and either delete the row
entirely or replace it with up-to-date notarization guidance and the correct
scoring/columns; ensure any references to the CodeNotary bonus elsewhere in the
document are updated or removed so the table and narrative remain consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c1c8fb45-40ff-499f-ae3b-6300034de275
📒 Files selected for processing (3)
docs/apps/configuration.mddocs/apps/presentation.mddocs/apps/tutorial.md
💤 Files with no reviewable changes (1)
- docs/apps/tutorial.md
| | `slug` | string | Slug of the app. This needs to be unique in the scope of the [repository](/docs/apps/repository) that the app is published in and URI friendly. | | ||
| | `description` | string | Description of the app. | ||
| | `arch` | list | A list of supported architectures: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`. | ||
| | `arch` | list | A list of supported architectures: `aarch64`, `amd64`. |
Contributor
There was a problem hiding this comment.
Fix markdown table pipe style (MD055)
Lines 131 and 172 are missing trailing |, which is causing markdownlint MD055 warnings.
Suggested fix
-| `arch` | list | A list of supported architectures: `aarch64`, `amd64`.
+| `arch` | list | A list of supported architectures: `aarch64`, `amd64`. |
-| `image` | string | | For use with container registries. Set this to the generic (multi-arch) image name, e.g. `ghcr.io/my-org/my-app`. The `{arch}` placeholder is still supported as a compatibility fallback for per-architecture image names (e.g. `ghcr.io/my-org/{arch}-my-app`). If you use this option, set the active Docker tag using the `version` option.
+| `image` | string | | For use with container registries. Set this to the generic (multi-arch) image name, e.g. `ghcr.io/my-org/my-app`. The `{arch}` placeholder is still supported as a compatibility fallback for per-architecture image names (e.g. `ghcr.io/my-org/{arch}-my-app`). If you use this option, set the active Docker tag using the `version` option. |Also applies to: 172-172
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 131-131: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/apps/configuration.md` at line 131, The markdown table row for the
`arch` entry is missing a trailing pipe causing MD055 warnings; fix by adding
the missing trailing `|` at the end of the `| `arch` | list | A list of
supported architectures: `aarch64`, `amd64`. |` row and likewise add a trailing
`|` to the other affected row around line 172 so all table rows consistently
start and end with `|`.
agners
requested changes
Apr 2, 2026
blog/2026-04-02-builder-migration.md
Outdated
| --docker-password ${{ secrets.DOCKER_PASSWORD }} | ||
| ``` | ||
|
|
||
| ### After (composite actions) |
Member
There was a problem hiding this comment.
This Before/After is a bit weird, especially since the After then goes on mostly talking about build.yaml migration.
To me a structure like this would make more sense:
## Migration process
### Update Dockerfiles
Move content from `build.yaml` to Dockerfile....
### Update GitHub action workflows
Replace the previous action `home-assistant/builder@master` with...
I think its also not ideal that we have the YAML of the old actions in the post, but the new ones are just linked 😅 I'd not even show the old yaml at all, people copy stuff without reading, and it doesn't add that much value. I'd just mention that home-assistant/builder@master steps need to go, and then link to the new code.
agners
approved these changes
Apr 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed change
Document the recent changes in how apps and other HA containers are built and update docs where they were deprecated (e.g. still mentioning Codenotary).
Add blog post describing the changes in bigger picture and link it from the old 2020 post that described how the builder action can be used.
Closes #3001, closes #178, closes #803, closes #1939, closes #2026
Type of change
Checklist
Additional information
Summary by CodeRabbit