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.