Skip to content
Public template

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

DoYouHost ESPHome Project Template

Template for creating new ESPHome projects in the DoYouHost organization. The CI pipeline (build → pre-release → R2 → beta → production promotion) is shared via DoYouHost/workflows and DoYouHost/ESPHomeTemplates.

Initializing a new project

  1. Create a new repository from this template (GitHub: Use this template).
  2. Edit project.yaml — this is the only file containing project-level metadata consumed by the workflows:
    • project_name
    • r2_directory
    • esphome_version
    • files (list of ESPHome YAML entry points)
    • r2_cleanup_days
  3. Rename the skeleton esp32-template.yml to match files[0] from project.yaml, then fill in the project-specific configuration.
  4. Generate a fresh OTA_PASSWORD in substitutions. There is no API key to generate — see Provisioning below.
  5. Update the dashboard_import.package_import_url and the manifest URLs to point at the new repository / R2 directory.
  6. Reset version.txt to your starting version (e.g. 2026.1.0) and start a fresh CHANGELOG.md.
  7. In static/_config.yaml, leave title: as-is — it is rewritten by the publish-pages workflow using project_name from project.yaml.

Provisioning

The skeleton config ships unprovisioned: api: carries an empty encryption: block (no key:) and wifi: carries no station credentials, so both are set on first connection instead of being baked into the firmware. provisioning: bounds how long the device accepts that setup.

Consequences worth knowing:

  • The window lives in RAM only. Once it expires the device stops accepting provisioning until it is power-cycled — no reflash needed.
  • Reboot timeouts are suppressed while the device is unprovisioned, so it will not silently reboot (and reopen the window) mid-setup.
  • Putting a key: back under encryption:, or ssid:/password: under wifi:, makes the window pointless; ESPHome emits a warning at compile time when it sees that combination.
  • Requires ESPHome 2026.7.0 or newer — provisioning: does not exist in earlier releases, so esphome_version in project.yaml must not be pinned below it.

Required secrets

Configure these secrets in the new repository (or inherit from the org):

  • DOYOUHOST_PAT — used to publish releases and dispatch follow-up workflows
  • CF_ACCOUNT_ID, CF_ACCESS_KEY_ID, CF_SECRET_ACCESS_KEY, CF_BUCKET_NAME — Cloudflare R2 credentials for upload / promote / cleanup

Triggering a build

Workflows only build when explicitly requested:

  • A push or PR whose first line begins with BUILD: / build:
  • A manual workflow_dispatch run

Workflows

  • build-and-pre-release.yaml — builds firmware, creates a pre-release on GitHub, uploads artifacts to R2, promotes to the beta channel.
  • promote-to-prod.yaml — fires when a GitHub release is marked as released; promotes the matching artifacts in R2 to production and triggers a Pages rebuild.
  • publish-pages.yaml — builds and deploys the GitHub Pages landing page with embedded firmware downloads.
  • r2-cleanup.yaml — weekly cleanup of stale artifacts in R2.

How shared parameters work

project.yaml is the single source of truth. The composite action at .github/actions/load-project-config reads it once per workflow run and exposes the values as job outputs. Workflows reference those outputs instead of hard-coding strings, so a new project only needs to edit project.yaml to wire up the entire pipeline.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors