Home Assistant to an agentic PR¶
The job: Hitachi CSNet Home is a custom integration for Home Assistant. Every month Home Assistant ships a release that can break custom integrations. The maintainer wants, the moment a release lands:
- the integration's tests to run against that exact version;
- an AI review of the release notes and of the Home Assistant APIs the integration builds on;
- a fix PR prepared by an agent, once a human approves it.
Before Angelia, the repository polled PyPI every six hours from a cron job. With Angelia, Home Assistant's GitHub release pushes the work.
sequenceDiagram
participant HA as github.com/home-assistant/core
participant A as Angelia
participant R as csnet-home (GitHub Actions)
participant C as Claude
participant M as Maintainer
HA->>A: release 2026.12.0b0 (seen within 30 min)
A->>A: calver diff, policy, 1 h cooldown
A->>R: repository_dispatch "ha-release" + client_payload
R->>R: install HA 2026.12.0b0, import smoke test, pytest
R->>C: review release notes + HA API diff (no tools, read-only)
C-->>R: compatibility report
R->>M: issue "Home Assistant 2026.12 compatibility review"
M->>R: label ha-review:fix
R->>C: prepare a patch (tools confined to the integration and tests)
R->>M: pull request, for human review
On the Angelia side¶
version: 1
sinks:
- name: csnet-home-ci
kind: github-dispatch
config:
repo: mmornati/home-assistant-csnet-home
token_ref: gh-dispatch-csnet # fine-grained PAT: Contents read/write on that repo only
event_type: ha-release
watches:
- name: home-assistant
source: github-release
coordinates: { repo: home-assistant/core }
scheme: calver # 2026.11.1, 2026.12.0b0
interval: 30m
labels: { consumer: csnet-home }
policy:
prerelease: include # betas too: find breakage before users do
subscriptions:
- name: ha-to-csnet-home
sink: csnet-home-ci
filter:
labels: { consumer: csnet-home }
type: [release.published, release.prerelease]
policy:
cooldown: 1h # let the PyPI wheel land; drop it if yanked
sources:
github-release:
token_env: GITHUB_TOKEN # any token: public reads only need one to lift the rate limit
angelia secret set gh-dispatch-csnet --from-file pat.txt --host api.github.com
angelia config check --config angelia.yaml --watches watches.yaml
Give the GitHub source a token
home-assistant/core has hundreds of releases, so the first full scan needs several pages. Without a token,
GitHub allows 60 requests an hour and the scan cannot finish (netguard: rate limit wait for api.github.com
would pass the deadline). With a token, an unchanged repository costs nothing afterwards.
Why each line is there:
scheme: calvermakes2026.12.0b0a pre-release of2026.12.0and computes real bumps between dates.prerelease: includesends betas, which is when breakage is cheapest to fix.cooldown: 1hon the subscription only: Home Assistant publishes the GitHub release a little before the PyPI wheel, and a release pulled within the hour never reaches CI.event_type: ha-releaselets the repository listen for exactly this, and nothing else Angelia might send.
On the repository side¶
One workflow listens for the dispatch, tests the exact version, and starts the review when the monthly release has none yet.
name: HA Release from Angelia
'on':
repository_dispatch:
types: [ha-release]
permissions:
contents: read
concurrency: # a retried delivery carries the same event id
group: angelia-${{ github.event.client_payload.event_id }}
jobs:
validate:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.check.outputs.version }}
release: ${{ steps.check.outputs.release }}
steps:
- uses: actions/checkout@v4
- id: check
env: # untrusted: through env, then validated
PACKAGE: ${{ github.event.client_payload.package }}
VERSION: ${{ github.event.client_payload.version }}
run: |
[ "$PACKAGE" = "home-assistant/core" ] || { echo "::error::unexpected package"; exit 1; }
[[ "$VERSION" =~ ^20[0-9]{2}\.[0-9]+\.[0-9]+(b[0-9]+)?$ ]] || { echo "::error::bad version"; exit 1; }
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
echo "release=$(echo "$VERSION" | cut -d. -f1,2)" >> "$GITHUB_OUTPUT"
test:
needs: validate
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: '3.14' }
- run: scripts/ci/install_ha.sh "${{ needs.validate.outputs.version }}" tests
- run: python scripts/ci/import_smoke.py
- run: pytest tests/ -q --tb=short
review:
needs: [validate, test]
if: always() && needs.validate.result == 'success'
runs-on: ubuntu-latest
permissions: { actions: write, issues: read }
steps:
- env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
VERSION: ${{ needs.validate.outputs.version }}
RELEASE: ${{ needs.validate.outputs.release }}
run: |
FOUND=$(gh issue list --label ha-release-review --state all --limit 1 \
--search "in:title \"Home Assistant ${RELEASE} compatibility review\"" --json number --jq length)
[ "$FOUND" = "1" ] && { echo "already reviewed"; exit 0; }
gh workflow run ha-release-review.yaml -f version="$VERSION"
The complete file, with a PyPI wait and a job summary, is in the repository.
The agentic part, kept on a leash¶
The review and the fix are two existing workflows of the repository, built so that third-party text (release notes, blog posts) can shape a report but never trigger an action:
| Workflow | What the model can do | Who decides |
|---|---|---|
ha-release-review.yaml |
one Messages API call, no tools, from a job with contents: read; a separate job without a model opens the issue |
automatic, once per monthly release |
ha-review-fix.yaml |
tools confined to custom_components/ and tests/, plus pytest; produces a patch, a separate job checks the paths and opens the PR |
a maintainer adds the ha-review:fix label |
The result is always a pull request for human review, never a merge.
Tested end to end¶
On 16 November 2026 this exact configuration (Angelia v0.2.0, with a local mirror of the Home Assistant release
list so that 2026.11.1 appeared as new) emitted
github-release:home-assistant/core@2026.11.1, bump: patch from 2026.11.0, scheme: calver, and GitHub
accepted the dispatch with 204.
The run it started validated the
payload, installed Home Assistant 2026.11.1, passed the import smoke test, and skipped the Claude review because
2026.11 already had one. The unit tests waited, as designed, for pytest-homeassistant-custom-component to publish
a harness for that version.
Try it without waiting for a release¶
The first check of a watch is a baseline, so Angelia stays silent until Home Assistant's next release. To see the chain end to end today, trigger the same dispatch by hand with the payload Angelia would send:
gh api repos/mmornati/home-assistant-csnet-home/dispatches \
-f event_type=ha-release \
-F 'client_payload[event_id]=manual-test-1' \
-F 'client_payload[source]=github-release' \
-F 'client_payload[package]=home-assistant/core' \
-F 'client_payload[version]=2026.11.1' \
-F 'client_payload[previous_version]=2026.11.0' \
-F 'client_payload[bump]=patch'
Adapt it to your integration¶
Change the repository, the label and the tests; keep the shape: Angelia detects and delivers, the repository validates the payload, tests run first, the model reads without tools, a human approves before an agent writes.