# Powerforge Homeassistant Release

> Onboard, operate, verify, or recover GitHub releases for Home Assistant custom integrations and HACS Lovelace plugins using PowerForge. Use for thin receiver workflows, release labels, synchronized manifest/pyproject/package versions, HACS assets, or failed post-merge release runs.

- Skill: `evotecit/powerforge-homeassistant-release` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add evotecit/powerforge-homeassistant-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evotecit/powerforge-homeassistant-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: evotecit (https://skillmd.com/u/evotecit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/evotecit/powerforge-homeassistant-release

---


# PowerForge Home Assistant Release

Use PowerForge as the release owner. A receiver repository should contain only the event trigger and a call to `.github/workflows/powerforge-homeassistant-release.yml`; do not copy version, npm, zip, git, GitHub API, retry, or verification logic into it.

## Onboard a repository

1. Confirm the repository has `hacs.json` and exactly one supported layout:
   - integration: one `custom_components/<domain>/manifest.json`, with an optional matching `[project] version` in `pyproject.toml`;
   - Lovelace plugin: `package.json`, required `package-lock.json`, and `hacs.json` `filename`.
2. Inspect the existing validation workflow and latest GitHub release. The PR head must have at least one completed successful, neutral, or skipped check run.
3. Add only the `pull_request_target` receiver workflow documented in `Docs/PowerForge.HomeAssistantRelease.md`. Pin the reusable workflow to the full immutable SHA of a reviewed PSPublishModule release; a release tag may appear only as a maintenance comment. Keep the trigger on `closed`: the trusted default-branch workflow must handle fork and Dependabot merges without checking out or executing pull-request code with its write token.
4. Give the job `actions: read`, `checks: read`, `contents: write`, and `pull-requests: read`. Keep the workflow-dispatch PR number input textual and use the canonical `format` expression when passing either event source into the reusable workflow. Pass the merge SHA, default branch, and `github.token` unchanged.
5. Add the `release:none`, `release:patch`, `release:minor`, and `release:major` labels if the repository does not have them.
6. Validate the receiver YAML and open a release-ready PR. Use a release label only when that onboarding PR should intentionally prove a live release.

## Operate releases

- With no release label, product/config/dependency changes increment patch; docs, tests, workflows, and maintainer metadata do not release.
- Exactly one release label overrides that default. Conflicting release labels fail closed.
- PowerForge queues every merge trigger and runs three isolated jobs: privileged metadata prepare/push without receiver commands, read-only exact-commit build without write credentials, then privileged publish without receiver checkout or execution. It verifies the marker, tag target, conflict provenance, and required asset.
- Published releases use GitHub-generated change and contributor notes. PowerForge
  prepends only hidden provenance metadata needed for safe retry and recovery.
- Treat three-part versions as the public contract. Do not introduce four-part consumer versions.

## Recover a failed run

Rerun the failed Actions job first. PowerForge resumes safely:

- a release containing the source PR marker is verified and reused;
- metadata ahead of the latest release is resumed only when the requested PR owns the prepared release commit;
- an existing tag/release is reused and same-named assets are replaced only after marker and commit preflight;
- missing historical assets are rebuilt from a fresh read-only checkout of the exact tag commit;
- a tag pointing at the wrong commit or a missing required asset fails verification.

For a manual recovery, dispatch the receiver workflow with the original merged PR number, its merge SHA, and the same increment decision. The receiver's textual PR-number contract must match the canonical example; a numeric workflow-dispatch input is not compatible with the reusable-call graph. Do not hand-edit a second version bump or manually create a competing release.

## Keep the boundary thin

When another Home Assistant repository needs a new release rule, layout, artifact, or recovery case, implement and test it in `PowerForge`, update the reusable action/workflow and runbook, then repin receivers. A receiver-specific workaround is acceptable only for product-owned validation before the shared release call.