builder.yml

name: Build images

# yamllint disable-line rule:truthy
on:
  workflow_dispatch:
  release:
    types: ["published"]
  schedule:
    - cron: "0 2 * * *"

env:
  BUILD_TYPE: core
  PIP_TIMEOUT: 60
  UV_HTTP_TIMEOUT: 60
  UV_SYSTEM_PYTHON: "true"
  # Base image version from https://github.com/home-assistant/docker
  # If python version changes in the base image, update .python-version accordingly to match the new Python version.
  BASE_IMAGE_VERSION: "2026.10.0"
  ARCHITECTURES: '["amd64", "aarch64"]'
  MACHINES: >-
    ["generic-x86-64", "khadas-vim3", "odroid-c2", "odroid-c4", "odroid-m1",
    "odroid-n2", "qemuarm-64", "qemux86-64", "raspberrypi3-64",
    "raspberrypi4-64", "raspberrypi5-64", "yellow", "green"]

permissions: {}

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  init:
    name: Initialize build
    if: github.repository_owner == 'home-assistant'
    runs-on: ubuntu-26.04
    permissions:
      contents: read # To check out the repository
    outputs:
      version: ${{ steps.version.outputs.version }}
      channel: ${{ steps.version.outputs.channel }}
      publish: ${{ steps.version.outputs.publish }}
      architectures: ${{ env.ARCHITECTURES }}
      machines: ${{ env.MACHINES }}
      base_image_version: ${{ env.BASE_IMAGE_VERSION }}
    steps:
      - name: Checkout the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version-file: ".python-version"

      - name: Get version
        id: version
        uses: home-assistant/actions/helpers/version@master # zizmor: ignore[unpinned-uses]
        with:
          type: ${{ env.BUILD_TYPE }}

      - name: Verify version
        uses: home-assistant/actions/helpers/verify-version@master # zizmor: ignore[unpinned-uses]
        with:
          ignore-dev: true

      - name: Fail if translations files are checked in
        run: |
          if [ -n "$(find homeassistant/components/*/translations -type f)" ]; then
              echo "Translations files are checked in, please remove the following files:"
              find homeassistant/components/*/translations -type f
              exit 1
          fi

      - name: Download Translations
        run: python3 -m script.translations download
        env:
          LOKALISE_TOKEN: ${{ secrets.LOKALISE_TOKEN }} # zizmor: ignore[secrets-outside-env]

      - name: Archive translations
        shell: bash
        run: find ./homeassistant/components/*/translations -name "*.json" | tar zcvf translations.tar.gz -T -

      - name: Upload translations
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: translations
          path: translations.tar.gz
          if-no-files-found: error

  build_base:
    name: Build ${{ matrix.arch }} base core image
    if: github.repository_owner == 'home-assistant'
    needs: init
    runs-on: ${{ matrix.os }}
    permissions:
      contents: read # To check out the repository
      packages: write # To push to GHCR
      id-token: write # For cosign signing
    strategy:
      fail-fast: false
      matrix:
        arch: ${{ fromJson(needs.init.outputs.architectures) }}
        include:
          - arch: amd64
            os: ubuntu-26.04
          - arch: aarch64
            os: ubuntu-26.04-arm
    steps:
      - name: Checkout the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Download nightly wheels of frontend
        if: needs.init.outputs.channel == 'dev'
        uses: dawidd6/action-download-artifact@eab87c9830c39eff17e5a6eadb20bfb4bc880477 # v27
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          repo: home-assistant/frontend
          branch: dev
          workflow: nightly.yaml
          workflow_conclusion: success
          name: wheels

      - name: Download nightly wheels of intents
        if: needs.init.outputs.channel == 'dev'
        uses: dawidd6/action-download-artifact@eab87c9830c39eff17e5a6eadb20bfb4bc880477 # v27
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          repo: OHF-Voice/intents-package
          branch: main
          workflow: nightly.yaml
          workflow_conclusion: success
          name: package

      - name: Set up Python
        if: needs.init.outputs.channel == 'dev'
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version-file: ".python-version"

      - name: Adjust nightly version
        if: needs.init.outputs.channel == 'dev'
        shell: bash
        env:
          UV_PRERELEASE: allow
          VERSION: ${{ needs.init.outputs.version }}
        run: |
          python3 -m pip install "$(grep '^uv' < requirements.txt)"
          uv pip install packaging tomli
          uv pip install .
          python3 script/version_bump.py nightly --set-nightly-version "${VERSION}"

          if [[ "$(ls home_assistant_frontend*.whl)" =~ ^home_assistant_frontend-(.*)-py3-none-any.whl$ ]]; then
            echo "Found frontend wheel, setting version to: ${BASH_REMATCH[1]}"
            frontend_version="${BASH_REMATCH[1]}" yq \
              --inplace e -o json \
              '.requirements = ["home-assistant-frontend=="+env(frontend_version)]' \
              homeassistant/components/frontend/manifest.json

            sed -i "s|home-assistant-frontend==.*|home-assistant-frontend==${BASH_REMATCH[1]}|" \
              homeassistant/package_constraints.txt

            sed -i "s|home-assistant-frontend==.*||" requirements_all.txt
          fi

          if [[ "$(ls home_assistant_intents*.whl)" =~ ^home_assistant_intents-(.*)-py3-none-any.whl$ ]]; then
            echo "Found intents wheel, setting version to: ${BASH_REMATCH[1]}"
            yq \
              --inplace e -o json \
              'del(.requirements[] | select(contains("home-assistant-intents")))' \
              homeassistant/components/conversation/manifest.json

            intents_version="${BASH_REMATCH[1]}" yq \
              --inplace e -o json \
              '.requirements += ["home-assistant-intents=="+env(intents_version)]' \
              homeassistant/components/conversation/manifest.json

            sed -i "s|home-assistant-intents==.*|home-assistant-intents==${BASH_REMATCH[1]}|" \
              homeassistant/package_constraints.txt

            sed -i "s|home-assistant-intents==.*||" requirements_all.txt requirements.txt
          fi

      - name: Download translations
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: translations

      - name: Extract translations
        run: |
          tar xvf translations.tar.gz
          rm translations.tar.gz

      - name: Write meta info file
        shell: bash
        run: |
          echo "${GITHUB_SHA};${GITHUB_REF};${GITHUB_EVENT_NAME};${GITHUB_ACTOR}" > rootfs/OFFICIAL_IMAGE

      - name: Build base image
        uses: home-assistant/builder/actions/build-image@7412f0023ea9b6e58e8bb5059f1660f51376f49a # 2026.09.0
        with:
          arch: ${{ matrix.arch }}
          build-args: |
            BUILD_FROM=ghcr.io/home-assistant/${{ matrix.arch }}-homeassistant-base:${{ needs.init.outputs.base_image_version }}
          cache-gha: false
          container-registry-password: ${{ secrets.GITHUB_TOKEN }}
          cosign-base-identity: "https://github.com/home-assistant/docker/.*"
          cosign-base-verify: ghcr.io/home-assistant/${{ matrix.arch }}-homeassistant-base:${{ needs.init.outputs.base_image_version }}
          image: ghcr.io/home-assistant/${{ matrix.arch }}-homeassistant
          image-tags: ${{ needs.init.outputs.version }}
          push: true
          version: ${{ needs.init.outputs.version }}

  build_machine:
    name: Build ${{ matrix.machine }} machine core image
    if: github.repository_owner == 'home-assistant'
    needs: ["init", "build_base"]
    runs-on: ${{ matrix.runs-on }}
    permissions:
      contents: read # To check out the repository
      packages: write # To push to GHCR
      id-token: write # For cosign signing
    strategy:
      matrix:
        machine: ${{ fromJson(needs.init.outputs.machines) }}
        include:
          # Default: aarch64 on native ARM runner
          - arch: aarch64
            runs-on: ubuntu-26.04-arm
          # Overrides for amd64 machines
          - machine: generic-x86-64
            arch: amd64
            runs-on: ubuntu-26.04
          - machine: qemux86-64
            arch: amd64
            runs-on: ubuntu-26.04
    steps:
      - name: Checkout the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Compute extra tags
        id: tags
        shell: bash
        env:
          VERSION: ${{ needs.init.outputs.version }}
        run: |
          if [[ "${VERSION}" =~ d ]]; then
            echo "extra_tags=dev" >> "$GITHUB_OUTPUT"
          elif [[ "${VERSION}" =~ b ]]; then
            echo "extra_tags=beta" >> "$GITHUB_OUTPUT"
          else
            echo "extra_tags=stable" >> "$GITHUB_OUTPUT"
          fi

      - name: Build machine image
        uses: home-assistant/builder/actions/build-image@7412f0023ea9b6e58e8bb5059f1660f51376f49a # 2026.09.0
        with:
          arch: ${{ matrix.arch }}
          build-args: |
            BUILD_FROM=ghcr.io/home-assistant/${{ matrix.arch }}-homeassistant:${{ needs.init.outputs.version }}
          cache-gha: false
          container-registry-password: ${{ secrets.GITHUB_TOKEN }}
          context: machine/
          cosign-base-identity: "https://github.com/home-assistant/core/.*"
          cosign-base-verify: ghcr.io/home-assistant/${{ matrix.arch }}-homeassistant:${{ needs.init.outputs.version }}
          file: machine/${{ matrix.machine }}
          image: ghcr.io/home-assistant/${{ matrix.machine }}-homeassistant
          image-tags: |
            ${{ needs.init.outputs.version }}
            ${{ steps.tags.outputs.extra_tags }}
          push: true
          version: ${{ needs.init.outputs.version }}

  run_e2e_tests_base:
    name: Run E2E tests on base images
    if: github.repository_owner == 'home-assistant'
    needs: ["init", "build_base"]
    uses: $/.github/workflows/e2e-tests.yml
    with:
      version: ${{ needs.init.outputs.version }}
      image_prefixes: ${{ needs.init.outputs.architectures }}

  run_e2e_tests_machine:
    name: Run E2E tests on machine images
    if: github.repository_owner == 'home-assistant'
    needs: ["init", "build_machine"]
    uses: $/.github/workflows/e2e-tests.yml
    with:
      version: ${{ needs.init.outputs.version }}
      image_prefixes: ${{ needs.init.outputs.machines }}

  publish_ha:
    name: Publish version files
    environment: ${{ needs.init.outputs.channel }}
    if: github.repository_owner == 'home-assistant'
    needs: ["init", "build_machine", "run_e2e_tests_machine"]
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    steps:
      - name: Checkout the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Initialize git
        uses: home-assistant/actions/helpers/git-init@master # zizmor: ignore[unpinned-uses]
        with:
          name: ${{ secrets.GIT_NAME }}
          email: ${{ secrets.GIT_EMAIL }}
          token: ${{ secrets.GIT_TOKEN }}

      - name: Update version file
        uses: home-assistant/actions/helpers/version-push@master # zizmor: ignore[unpinned-uses]
        with:
          key: "homeassistant[]"
          key-description: "Home Assistant Core"
          version: ${{ needs.init.outputs.version }}
          channel: ${{ needs.init.outputs.channel }}
          exclude-list: '["odroid-xu","qemuarm","qemux86","raspberrypi","raspberrypi2","raspberrypi3","raspberrypi4","tinker"]'

      - name: Update version file (stable -> beta)
        if: needs.init.outputs.channel == 'stable'
        uses: home-assistant/actions/helpers/version-push@master # zizmor: ignore[unpinned-uses]
        with:
          key: "homeassistant[]"
          key-description: "Home Assistant Core"
          version: ${{ needs.init.outputs.version }}
          channel: beta
          exclude-list: '["odroid-xu","qemuarm","qemux86","raspberrypi","raspberrypi2","raspberrypi3","raspberrypi4","tinker"]'

  publish_container:
    name: Publish to ${{ matrix.registry }}
    environment: ${{ needs.init.outputs.channel }}
    if: github.repository_owner == 'home-assistant'
    needs: ["init", "build_base", "run_e2e_tests_base"]
    runs-on: ubuntu-26.04
    permissions:
      contents: read # To check out the repository
      packages: write # To push to GHCR
      id-token: write # For cosign signing
    strategy:
      fail-fast: false
      matrix:
        registry: ["ghcr.io/home-assistant", "docker.io/homeassistant"]
    steps:
      - name: Install Cosign
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      - name: Login to DockerHub
        if: matrix.registry == 'docker.io/homeassistant'
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to GitHub Container Registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Verify architecture image signatures
        shell: bash
        env:
          ARCHITECTURES: ${{ needs.init.outputs.architectures }}
          VERSION: ${{ needs.init.outputs.version }}
        run: |
          ARCHS=$(echo "${ARCHITECTURES}" | jq -r '.[]')
          for arch in $ARCHS; do
            echo "Verifying ${arch} image signature..."
            cosign verify \
              --certificate-oidc-issuer https://token.actions.githubusercontent.com \
              --certificate-identity-regexp https://github.com/home-assistant/core/.* \
              "ghcr.io/home-assistant/${arch}-homeassistant:${VERSION}"
          done
          echo "✓ All images verified successfully"

      # Generate all Docker tags based on version string
      # Version format: YYYY.MM.PATCH, YYYY.MM.PATCHbN (beta), or YYYY.MM.PATCH.devYYYYMMDDHHMM (dev)
      # Examples:
      #   2025.12.1     (stable)    -> tags: 2025.12.1, 2025.12, stable, latest, beta, rc
      #   2025.12.0b3   (beta)      -> tags: 2025.12.0b3, beta, rc
      #   2025.12.0.dev202511250240 -> tags: 2025.12.0.dev202511250240, dev
      - name: Generate Docker metadata
        id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ matrix.registry }}/home-assistant
          sep-tags: ","
          tags: |
            type=raw,value=${{ needs.init.outputs.version }},priority=9999
            type=raw,value=dev,enable=${{ contains(needs.init.outputs.version, 'd') }}
            type=raw,value=beta,enable=${{ !contains(needs.init.outputs.version, 'd') }}
            type=raw,value=rc,enable=${{ !contains(needs.init.outputs.version, 'd') }}
            type=raw,value=stable,enable=${{ !contains(needs.init.outputs.version, 'd') && !contains(needs.init.outputs.version, 'b') }}
            type=raw,value=latest,enable=${{ !contains(needs.init.outputs.version, 'd') && !contains(needs.init.outputs.version, 'b') }}
            type=semver,pattern={{major}}.{{minor}},value=${{ needs.init.outputs.version }},enable=${{ !contains(needs.init.outputs.version, 'd') && !contains(needs.init.outputs.version, 'b') }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      - name: Copy architecture images to DockerHub
        if: matrix.registry == 'docker.io/homeassistant'
        shell: bash
        env:
          ARCHITECTURES: ${{ needs.init.outputs.architectures }}
          VERSION: ${{ needs.init.outputs.version }}
        run: |
          # Use imagetools to copy image blobs directly between registries
          # This preserves provenance/attestations and seems to be much faster than pull/push
          ARCHS=$(echo "${ARCHITECTURES}" | jq -r '.[]')
          for arch in $ARCHS; do
            echo "Copying ${arch} image to DockerHub..."
            for attempt in 1 2 3; do
              if docker buildx imagetools create \
                --tag "docker.io/homeassistant/${arch}-homeassistant:${VERSION}" \
                "ghcr.io/home-assistant/${arch}-homeassistant:${VERSION}"; then
                break
              fi
              echo "Attempt ${attempt} failed, retrying in 10 seconds..."
              sleep 10
              if [ "${attempt}" -eq 3 ]; then
                echo "Failed after 3 attempts"
                exit 1
              fi
            done
            cosign sign --yes "docker.io/homeassistant/${arch}-homeassistant:${VERSION}"
          done

      - name: Create and push multi-arch manifests
        shell: bash
        env:
          ARCHITECTURES: ${{ needs.init.outputs.architectures }}
          REGISTRY: ${{ matrix.registry }}
          VERSION: ${{ needs.init.outputs.version }}
          META_TAGS: ${{ steps.meta.outputs.tags }}
        run: |
          # Build list of architecture images dynamically
          ARCHS=$(echo "${ARCHITECTURES}" | jq -r '.[]')
          ARCH_IMAGES=()
          for arch in $ARCHS; do
            ARCH_IMAGES+=("${REGISTRY}/${arch}-homeassistant:${VERSION}")
          done

          # Build list of all tags for single manifest creation
          # Note: Using sep-tags=',' in metadata-action for easier parsing
          TAG_ARGS=()
          IFS=',' read -ra TAGS <<< "${META_TAGS}"
          for tag in "${TAGS[@]}"; do
            TAG_ARGS+=("--tag" "${tag}")
          done

          # Create manifest with ALL tags in a single operation (much faster!)
          echo "Creating multi-arch manifest with tags: ${TAGS[*]}"
          docker buildx imagetools create "${TAG_ARGS[@]}" "${ARCH_IMAGES[@]}"

          # Sign each tag separately (signing requires individual tag names)
          echo "Signing all tags..."
          for tag in "${TAGS[@]}"; do
            echo "Signing ${tag}"
            cosign sign --yes "${tag}"
          done

          echo "All manifests created and signed successfully"

  build_python:
    name: Build PyPi package
    environment: ${{ needs.init.outputs.channel }}
    needs: ["init", "build_base", "run_e2e_tests_base"]
    runs-on: ubuntu-26.04
    permissions:
      contents: read # To check out the repository
      id-token: write # For PyPI trusted publishing
    if: github.repository_owner == 'home-assistant' && needs.init.outputs.publish == 'true'
    steps:
      - name: Checkout the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version-file: ".python-version"

      - name: Download translations
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: translations

      - name: Extract translations
        run: |
          tar xvf translations.tar.gz
          rm translations.tar.gz

      - name: Build package
        shell: bash
        run: |
          # Remove dist, build, and homeassistant.egg-info
          # when build locally for testing!
          pip install build
          python -m build

      - name: Upload package to PyPI
        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
        with:
          skip-existing: true

  hassfest-image:
    name: Build and test hassfest image
    runs-on: ubuntu-26.04
    permissions:
      contents: read # To check out the repository
      packages: write # To push to GHCR
      attestations: write # For build provenance attestation
      id-token: write # For build provenance attestation
    needs: ["init"]
    if: github.repository_owner == 'home-assistant'
    env:
      HASSFEST_IMAGE_NAME: ghcr.io/home-assistant/hassfest
      HASSFEST_IMAGE_TAG: ghcr.io/home-assistant/hassfest:${{ needs.init.outputs.version }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Login to GitHub Container Registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build Docker image
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: . # So action will not pull the repository again
          file: ./script/hassfest/docker/Dockerfile
          load: true
          tags: ${{ env.HASSFEST_IMAGE_TAG }}

      - name: Run hassfest against core
        run: docker run --rm -v "${GITHUB_WORKSPACE}":/github/workspace "${HASSFEST_IMAGE_TAG}" --core-path=/github/workspace

      - name: Push Docker image
        if: needs.init.outputs.channel != 'dev' && needs.init.outputs.publish == 'true'
        id: push
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: . # So action will not pull the repository again
          file: ./script/hassfest/docker/Dockerfile
          push: true
          tags: ${{ env.HASSFEST_IMAGE_TAG }},${{ env.HASSFEST_IMAGE_NAME }}:latest

      - name: Generate artifact attestation
        if: needs.init.outputs.channel != 'dev' && needs.init.outputs.publish == 'true'
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-name: ${{ env.HASSFEST_IMAGE_NAME }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true