Skip to content

Commit dd86b0a

Browse files
saironagners
sairon
and
agners
authored
Deprecate usage of home-assistant/builder, update README (#279)
* Deprecate usage of `home-assistant/builder`, update README With the new actions added in #273, the old action and build container will no longer be maintained. To make the landing softer, especially for those repos that still use the discouraged `@master` action pinning, only print warnings until they migrate or pin the action to the old release. The references to the old action and builder usage are now removed from the README and a high-level description of the new workflow added. * Elaborate on legacy action deprecation Co-authored-by: Stefan Agner <stefan@agner.ch> --------- Co-authored-by: Stefan Agner <stefan@agner.ch>
1 parent a14edf3 commit dd86b0a

File tree

3 files changed

+85
-216
lines changed

3 files changed

+85
-216
lines changed

‎README.md‎

Lines changed: 77 additions & 216 deletions
Original file line numberDiff line numberDiff line change
@@ -1,247 +1,108 @@
1-
# Home Assistant builder
1+
# Home Assistant Builder
22

3-
_Multi-purpose cross-compile docker builder._
3+
_Tooling used for building of Home Assistant container images._
44

5-
## GitHub Action
5+
## Reusable GitHub Actions
66

7-
You can use this repository as a GitHub action to test and/or publish your builds.
7+
This repository provides a set of the following composable GitHub Actions for building, signing, and publishing multi-arch container images. They are designed to be used together in a workflow but some of them can be used standalone as well.
88

9-
Use the `with.args` key to pass in arguments to the builder, to see what arguments are supported you can look at the [arguments](#Arguments) section.
9+
### [`prepare-multi-arch-matrix`](actions/prepare-multi-arch-matrix/action.yml)
1010

11-
### Cosign support
11+
Takes a JSON array of architectures (e.g., `["amd64", "aarch64"]`) and an image name, and outputs a GitHub Actions build matrix suited for use with `build-image`.
1212

13-
You can use cosign to signing and verify the build chain. To sign the image, use `--cosign` and attach following options to the github action:
13+
### [`build-image`](actions/build-image/action.yml)
1414

15-
```yaml
16-
jobs:
17-
build:
18-
name: Test build
19-
runs-on: ubuntu-latest
20-
permissions:
21-
contents: read
22-
packages: write
23-
id-token: write
24-
```
25-
26-
For keep a trust-chain during the built, you need set `identity` and `base_identity` to your build.yml
15+
Builds a single-arch container image using Docker Buildx with optional push and Cosign signing. Supports GHA and registry-based build caching, base image signature verification, and custom build args/labels. Outputs the image digest.
2716

28-
### Test action example
17+
### [`publish-multi-arch-manifest`](actions/publish-multi-arch-manifest/action.yml)
2918

30-
_Note: Replace `[version]` with the desired tag from the [releases](https://github.com/home-assistant/builder/releases) page._
19+
Combines per-architecture images (e.g., `amd64-myimage:latest`, `aarch64-myimage:latest`) into a single multi-arch manifest (e.g., `myimage:latest`) using `docker buildx imagetools create`. Optionally signs the resulting manifest with Cosign.
3120

32-
```yaml
33-
name: "Test"
21+
### [`cosign-verify`](actions/cosign-verify/action.yml)
3422

35-
on: [push, pull_request]
23+
Verifies Cosign signatures on container images with up to 5 retries and exponential backoff. Supports an allow-failure mode that emits a warning instead of failing. Used internally by `build-image` for cache and base image verification, but can also be used standalone.
3624

37-
jobs:
38-
build:
39-
name: Test build
40-
runs-on: ubuntu-latest
41-
steps:
42-
- name: Checkout the repository
43-
uses: actions/checkout@v6
44-
- name: Test build
45-
uses: home-assistant/builder@[version]
46-
with:
47-
args: |
48-
--test \
49-
--all \
50-
--target addon-folder \
51-
--docker-hub user-name-or-space-name
52-
```
25+
## Example workflow
5326

54-
### Publish action example
27+
The following example workflow builds multi-arch container images when a GitHub release is published. It prepares a build matrix, builds per-architecture images in parallel (e.g., `ghcr.io/owner/amd64-my-image`, `ghcr.io/owner/aarch64-my-image`), and then combines them into a single multi-arch manifest (`ghcr.io/owner/my-image`).
5528

5629
_Note: Replace `[version]` with the desired tag from the [releases](https://github.com/home-assistant/builder/releases) page._
5730

5831
```yaml
59-
name: "Publish"
32+
name: Build
6033

6134
on:
6235
release:
6336
types: [published]
6437

38+
env:
39+
ARCHITECTURES: '["amd64", "aarch64"]'
40+
IMAGE_NAME: my-image
41+
42+
permissions:
43+
contents: read
44+
6545
jobs:
66-
publish:
67-
name: Publish
46+
init:
47+
name: Initialize build
6848
runs-on: ubuntu-latest
49+
outputs:
50+
matrix: ${{ steps.matrix.outputs.matrix }}
6951
steps:
70-
- name: Checkout the repository
71-
uses: actions/checkout@v6
72-
- name: Login to DockerHub
73-
uses: docker/login-action@v3
74-
with:
75-
username: ${{ secrets.DOCKERHUB_USERNAME }}
76-
password: ${{ secrets.DOCKERHUB_TOKEN }}
77-
- name: Publish
78-
uses: home-assistant/builder@[version]
79-
with:
80-
args: |
81-
--all \
82-
--target addon-folder \
83-
--docker-hub user-name-or-space-name
84-
```
85-
86-
## Arguments
87-
88-
```
89-
Options:
90-
-h, --help
91-
Display this help and exit.
92-
93-
Repository / Data
94-
-r, --repository <REPOSITORY>
95-
Set git repository to load data from.
96-
-b, --branch <BRANCH>
97-
Set git branch for repository.
98-
-t, --target <PATH_TO_BUILD>
99-
Set local folder or path inside repository for build.
100-
101-
Version/Image handling
102-
-v, --version <VERSION>
103-
Overwrite version/tag of build.
104-
-i, --image <IMAGE_NAME>
105-
Overwrite image name of build / support {arch}.
106-
--release <VERSION>
107-
Additional version information like for base images.
108-
--release-tag
109-
Use this as main tag.
110-
--additional-tag
111-
Add additional tags that will be published
112-
--version-from <VERSION>
113-
Use this to set build_from tag if not specified.
114-
115-
Architecture (select at least one)
116-
--amd64
117-
Build for intel/amd 64bit.
118-
--aarch64
119-
Build for arm 64bit.
120-
121-
Build handling
122-
--test
123-
Disable push to dockerhub.
124-
--no-latest
125-
Do not tag images as latest.
126-
--no-cache
127-
Disable cache for the build (from latest).
128-
--self-cache
129-
Use same tag as cache tag instead latest.
130-
--cache-tag <TAG>
131-
Use a custom tag for the build cache.
132-
-d, --docker-hub <DOCKER_REPOSITORY>
133-
Set or overwrite the docker repository.
134-
--docker-hub-check
135-
Check if the version already exists before starting the build.
136-
--docker-user <USER>
137-
Username to login into docker with
138-
--docker-password <PASSWORD>
139-
Password to login into docker with
140-
141-
Use the host docker socket if mapped into container:
142-
/var/run/docker.sock
143-
144-
Internals:
145-
--addon
146-
Default on. Run all things for an addon build.
147-
--generic <VERSION>
148-
Build based on the build.json
149-
--base <VERSION>
150-
Build our base images.
151-
--machine <VERSION=ALL,X,Y>
152-
Build the machine based image for a release/landingpage.
153-
154-
Security:
155-
--cosign
156-
Enable signing images with cosign.
157-
--no-cosign-verify
158-
Disable image signature validation.
159-
```
160-
161-
## Local installation
162-
163-
amd64:
164-
165-
```bash
166-
docker pull ghcr.io/home-assistant/amd64-builder:latest
167-
```
52+
- uses: actions/checkout@v6
16853

169-
aarch64:
170-
171-
```bash
172-
docker pull ghcr.io/home-assistant/aarch64-builder:latest
173-
```
174-
175-
## Run
176-
177-
**For remote git repository:**
178-
179-
```bash
180-
docker run \
181-
--rm \
182-
--privileged \
183-
-v ~/.docker:/root/.docker \
184-
ghcr.io/home-assistant/amd64-builder:latest \
185-
--all \
186-
-t addon-folder \
187-
-r https://github.com/xy/addons \
188-
-b branchname
189-
```
190-
191-
**For local git repository:**
192-
193-
```bash
194-
docker run \
195-
--rm \
196-
--privileged \
197-
-v ~/.docker:/root/.docker \
198-
-v /my_addon:/data \
199-
ghcr.io/home-assistant/amd64-builder:latest \
200-
--all \
201-
-t /data
202-
```
203-
204-
## Docker Daemon
205-
206-
By default, the image will run docker-in-docker. You can use the host docker daemon by bind mounting the host docker socket to `/var/run/docker.sock` inside the container. For example, to do this with the _Local repository_ example above (assuming the host docker socket is at `/var/run/docker.sock`:
207-
208-
```bash
209-
docker run \
210-
--rm \
211-
--privileged \
212-
-v ~/.docker:/root/.docker \
213-
-v /var/run/docker.sock:/var/run/docker.sock:ro \
214-
-v /my_addon:/data \
215-
ghcr.io/home-assistant/amd64-builder:latest \
216-
--all \
217-
-t /data
218-
```
219-
220-
### Using shell alias
221-
222-
On Linux, it can be helpful to use a shell alias to run the builder from the
223-
current directory. E.g. by adding the following function to your `~/.bashrc`:
54+
- name: Get build matrix
55+
id: matrix
56+
uses: home-assistant/builder/actions/prepare-multi-arch-matrix@[version]
57+
with:
58+
architectures: ${{ env.ARCHITECTURES }}
59+
image-name: ${{ env.IMAGE_NAME }}
22460

225-
```
226-
function builder() {
227-
docker run \
228-
--rm \
229-
-it \
230-
--privileged \
231-
-v ${PWD}:/data \
232-
-v /var/run/docker.sock:/var/run/docker.sock:ro \
233-
ghcr.io/home-assistant/amd64-builder:latest --target /data $@
234-
}
235-
```
61+
build:
62+
name: Build ${{ matrix.arch }} image
63+
needs: init
64+
runs-on: ${{ matrix.os }}
65+
permissions:
66+
contents: read # To check out the code
67+
id-token: write # Write needed for Cosign signing (issue OIDC token for signing)
68+
packages: write # To push built images to GitHub Container Registry
69+
strategy:
70+
fail-fast: false
71+
matrix: ${{ fromJSON(needs.init.outputs.matrix) }}
72+
steps:
73+
- uses: actions/checkout@v6
23674

237-
This allows to build add-ons e.g. for a single architecture as follow:
238-
```
239-
$ cd /path/to/your/add-on
240-
$ builder --amd64 --docker-hub agners
75+
- name: Build image
76+
uses: home-assistant/builder/actions/build-image@[version]
77+
with:
78+
arch: ${{ matrix.arch }}
79+
container-registry-password: ${{ secrets.GITHUB_TOKEN }}
80+
image: ${{ matrix.image }}
81+
image-tags: |
82+
${{ github.event.release.tag_name }}
83+
latest
84+
push: "true"
85+
version: ${{ github.event.release.tag_name }}
86+
87+
manifest:
88+
name: Publish multi-arch manifest
89+
needs: [init, build]
90+
runs-on: ubuntu-latest
91+
permissions:
92+
id-token: write # Write needed for Cosign signing (issue OIDC token for signing)
93+
packages: write # To push the manifest to GitHub Container Registry
94+
steps:
95+
- name: Publish multi-arch manifest
96+
uses: home-assistant/builder/actions/publish-multi-arch-manifest@[version]
97+
with:
98+
architectures: ${{ env.ARCHITECTURES }}
99+
container-registry-password: ${{ secrets.GITHUB_TOKEN }}
100+
image-name: ${{ env.IMAGE_NAME }}
101+
image-tags: |
102+
${{ github.event.release.tag_name }}
103+
latest
241104
```
242105
243-
## Help
106+
## Legacy `home-assistant/builder` action
244107

245-
```bash
246-
docker run --rm --privileged ghcr.io/home-assistant/amd64-builder:latest --help
247-
```
108+
The `home-assistant/builder` action is deprecated and no longer maintained, the last official release was [2026.02.1](https://github.com/home-assistant/builder/blob/2026.02.1/README.md). If you came here because you see the warning in your action, migrate to the new actions above. We will remove the `home-assistant/builder` action soon, which will break your GitHub action if it is still using `home-assistant/builder@master` at that time.

‎action.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@ inputs:
1616
runs:
1717
using: "composite"
1818
steps:
19+
- name: Deprecation warning
20+
shell: bash
21+
run: |
22+
echo "::warning::The home-assistant/builder action is deprecated and no longer maintained. Please check https://github.com/home-assistant/builder and migrate the workflow to the new reusable actions."
23+
1924
- name: Install Cosign
2025
uses: sigstore/cosign-installer@ba7bc0a3fef59531c69a25acd34668d6d3fe6f22 # v4.1.0
2126
with:

‎builder.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -932,6 +932,9 @@ fi
932932

933933
#### Main ####
934934

935+
bashio::log.warning "This builder script is deprecated and no longer supported."
936+
bashio::log.warning "Please migrate your builds to use standard Dockerfiles with the new reusable GitHub Actions."
937+
935938
mkdir -p /data
936939

937940
# Setup docker env

0 commit comments

Comments
 (0)