fixes for esphome 2026.4 release

.github/instructions/esphome-release.instructions.md

@@ -0,0 +1,14 @@
+---
+description: "Use when updating ESPHome versions, firmware GitHub Actions, release tags, validation flows, or package refs in the esphome repository. Covers how to bump to a new ESPHome release, validate configs, and prepare a release tag."
+---
+# ESPHome Release Update Workflow
+
+- Keep one target ESPHome version across all release-related files. At minimum update `.github/workflows/build-firmware.yml`, `.github/workflows/validate-firmware.yml`, and `create_firmware.py`.
+- Never leave the build workflow on `version: latest`. Resolve the version once and pass the exact version into every build step.
+- Before editing YAML packages, validate all top-level `boneio-*.yaml` configs against the target image with Docker:
+  `docker run --rm -v "$PWD":/config ghcr.io/esphome/esphome:<version> config <file>`
+- Treat successful validation of all top-level configs as the release gate for ESPHome bumps.
+- Preserve the existing release tag format: `esphome-<esphome_version>-<build>`, for example `esphome-2026.4.0-b1`.
+- Keep GitHub Release notes explicit: mention the pinned ESPHome version, firmware bundle version, and the GitHub Pages catalog URL.
+- Do not modify generated `.esphome/` outputs as part of the version bump unless the task explicitly asks for committed build artifacts.
+- If a config fails on the new ESPHome version, fix the root YAML or shared package in `packages/` instead of weakening validation.

.github/workflows/build-firmware.yml

@@ -1,5 +1,8 @@
 name: Build ESPHome Firmware
 
+env:
+  DEFAULT_ESPHOME_VERSION: "2026.4.0"
+
 on:
   push:
     tags:
@@ -7,16 +10,47 @@ on:
   workflow_dispatch:
     inputs:
       esphome_version:
-        description: "ESPHome version (e.g., 2026.1.5)"
+        description: "ESPHome version (e.g., 2026.4.0)"
         required: true
-        default: "2026.1.5"
+        default: "2026.4.0"
       build:
         description: "Build number (e.g., b1)"
         required: true
         default: "b1"
 
 jobs:
+  resolve-version:
+    runs-on: ubuntu-latest
+    outputs:
+      esphome_version: ${{ steps.version.outputs.esphome_version }}
+      build: ${{ steps.version.outputs.build }}
+      full_version: ${{ steps.version.outputs.full_version }}
+      release_tag: ${{ steps.version.outputs.release_tag }}
+    steps:
+      - name: Resolve release version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            ESPHOME_VER="${{ github.event.inputs.esphome_version }}"
+            BUILD="${{ github.event.inputs.build }}"
+          else
+            TAG="${GITHUB_REF#refs/tags/esphome-}"
+            ESPHOME_VER=$(echo "$TAG" | sed 's/-b[0-9]*$//')
+            BUILD=$(echo "$TAG" | grep -oP 'b\d+$' || echo 'b1')
+          fi
+
+          if [ -z "$ESPHOME_VER" ]; then
+            ESPHOME_VER="${DEFAULT_ESPHOME_VERSION}"
+          fi
+
+          echo "esphome_version=$ESPHOME_VER" >> "$GITHUB_OUTPUT"
+          echo "build=$BUILD" >> "$GITHUB_OUTPUT"
+          echo "full_version=${ESPHOME_VER}-${BUILD}" >> "$GITHUB_OUTPUT"
+          echo "release_tag=esphome-${ESPHOME_VER}-${BUILD}" >> "$GITHUB_OUTPUT"
+          echo "Version: $ESPHOME_VER, Build: $BUILD"
+
   build:
+    needs: resolve-version
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -196,7 +230,7 @@ jobs:
         id: esphome-build
         with:
           yaml-file: ${{ matrix.yaml_file }}
-          version: latest
+          version: ${{ needs.resolve-version.outputs.esphome_version }}
           complete-manifest: true
 
       - name: Save build metadata
@@ -211,7 +245,8 @@ jobs:
             "version": "${{ matrix.version }}",
             "version_key": "${{ matrix.version_key }}",
             "output_option": "${{ matrix.output_option }}",
-            "chip_family": "${{ matrix.chip_family }}"
+            "chip_family": "${{ matrix.chip_family }}",
+            "esphome_version": "${{ needs.resolve-version.outputs.esphome_version }}"
           }
           METADATA_EOF
 
@@ -228,7 +263,9 @@ jobs:
           path: metadata/
 
   deploy:
-    needs: build
+    needs:
+      - resolve-version
+      - build
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -250,27 +287,10 @@ jobs:
           pattern: metadata-*
           merge-multiple: true
 
-      - name: Get version
-        id: version
-        run: |
-          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
-            ESPHOME_VER="${{ github.event.inputs.esphome_version }}"
-            BUILD="${{ github.event.inputs.build }}"
-          else
-            # Tag format: esphome-2026.1.5-b1
-            TAG="${GITHUB_REF#refs/tags/esphome-}"
-            ESPHOME_VER=$(echo "$TAG" | sed 's/-b[0-9]*$//')
-            BUILD=$(echo "$TAG" | grep -oP 'b\d+$' || echo 'b1')
-          fi
-          echo "esphome_version=$ESPHOME_VER" >> $GITHUB_OUTPUT
-          echo "build=$BUILD" >> $GITHUB_OUTPUT
-          echo "full_version=${ESPHOME_VER}-${BUILD}" >> $GITHUB_OUTPUT
-          echo "Version: $ESPHOME_VER, Build: $BUILD"
-
       - name: Prepare GitHub Pages content
         run: |
           mkdir -p gh-pages/firmware gh-pages/manifests release
-          export VERSION="${{ steps.version.outputs.full_version }}"
+          export VERSION="${{ needs.resolve-version.outputs.full_version }}"
           export BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
           export GITHUB_PAGES_URL="https://boneio-eu.github.io/esphome"
 
@@ -436,6 +456,44 @@ jobs:
           </html>
           EOF
 
+      - name: Generate release notes
+        run: |
+          python3 << 'PYTHON_EOF' > release-notes.md
+          import json
+          import glob
+
+          metadata_files = sorted(glob.glob("metadata/*.json"))
+          builds = []
+          for path in metadata_files:
+              with open(path) as handle:
+                  builds.append(json.load(handle))
+
+          esphome_version = "${{ needs.resolve-version.outputs.esphome_version }}"
+          build_number = "${{ needs.resolve-version.outputs.build }}"
+          full_version = "${{ needs.resolve-version.outputs.full_version }}"
+
+          board_lines = []
+          seen = set()
+          for build in builds:
+              label = f'- {build["board_name"]} {build["version"]} / {build["output_option"] or "Standard"} ({build["chip_family"]})'
+              if label not in seen:
+                  seen.add(label)
+                  board_lines.append(label)
+
+          print(f"# ESPHome {esphome_version} ({build_number})")
+          print()
+          print("## Build summary")
+          print()
+          print(f"- ESPHome version: `{esphome_version}`")
+          print(f"- Firmware bundle version: `{full_version}`")
+          print(f"- Firmware variants built: `{len(builds)}`")
+          print("- GitHub Pages catalog: `https://boneio-eu.github.io/esphome/firmware-catalog.json`")
+          print()
+          print("## Included firmware variants")
+          print()
+          print("\n".join(board_lines))
+          PYTHON_EOF
+
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
@@ -447,6 +505,6 @@ jobs:
         if: github.event_name == 'push'
         uses: softprops/action-gh-release@v2
         with:
-          name: "Firmware ${{ steps.version.outputs.esphome_version }} (${{ steps.version.outputs.build }})"
+          name: "Firmware ${{ needs.resolve-version.outputs.esphome_version }} (${{ needs.resolve-version.outputs.build }})"
+          body_path: release-notes.md
           files: release/*
-          generate_release_notes: true

.github/workflows/validate-firmware.yml

@@ -1,15 +1,20 @@
 name: Validate ESPHome Configs
 
+env:
+  ESPHOME_VERSION: "2026.4.0"
+
 on:
   push:
     branches: [main]
     paths:
       - "boneio-*.yaml"
       - "packages/**"
+      - ".github/workflows/validate-firmware.yml"
   pull_request:
     paths:
       - "boneio-*.yaml"
       - "packages/**"
+      - ".github/workflows/validate-firmware.yml"
 
 jobs:
   validate-urls:
@@ -24,14 +29,12 @@ jobs:
           for FILE in boneio-*.yaml; do
             BASENAME=$(basename "$FILE")
 
-            # Check package_import_url
-            URL=$(grep 'package_import_url:' "$FILE" 2>/dev/null | awk '{print $2}' | tr -d "'\"")
+            URL=$(grep 'package_import_url:' "$FILE" 2>/dev/null | awk '{print $2}' | sed "s/['\"]//g")
             if [ -z "$URL" ]; then
               echo "::warning::No package_import_url found in $FILE"
               continue
             fi
 
-            # Extract filename from URL (format: github://org/repo/path/file.yaml@ref)
             URL_FILE=$(echo "$URL" | sed 's|.*esphome/||' | sed 's|@.*||')
 
             if [ "$URL_FILE" != "$BASENAME" ]; then
@@ -39,7 +42,6 @@ jobs:
               ERRORS=$((ERRORS + 1))
             fi
 
-            # Check for double extensions
             if echo "$URL" | grep -q '\.yaml\.yaml'; then
               echo "::error file=$FILE::Double .yaml.yaml extension in package_import_url"
               ERRORS=$((ERRORS + 1))
@@ -52,3 +54,19 @@ jobs:
             exit 1
           fi
           echo "All package_import_url checks passed!"
+
+  validate-configs:
+    name: Validate configs on ESPHome 2026.4.0
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate top-level firmware configs
+        run: |
+          set -e
+          docker pull "ghcr.io/esphome/esphome:${ESPHOME_VERSION}"
+
+          for FILE in boneio-*.yaml; do
+            echo "Validating $FILE with ESPHome ${ESPHOME_VERSION}"
+            docker run --rm -v "$PWD":/config "ghcr.io/esphome/esphome:${ESPHOME_VERSION}" config "$FILE"
+          done