Add option to use frontend PR artifact to frontend integration by wendevlin · Pull Request #161291 · home-assistant/core

wendevlin · 2026-01-20T14:39:36Z

Proposed change

adds development_pr option to the frontend integration to easily try out PRs
- Downloads frontend PR artifact from github and uses it on startup

This should be an option for HAOS instances. For example the product team can easily test changes without the need to setup a dev env.

Documentation: frontend integration: Add support for development pull request and GitHub token home-assistant.io#43184
exclude from backup in supervisor: Add .cache to backup exclusion list supervisor#6483
dev docs: Add documentation for testing frontend PRs with GitHub artifacts developers.home-assistant#2938

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request: frontend integration: Add support for development pull request and GitHub token home-assistant.io#43184
Link to developer documentation pull request:
Link to frontend pull request:

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

Use dictionary mapping for HTTP error messages to eliminate code duplication. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Move GitHub error messages to module-level constants to avoid duplication across _get_pr_head_sha and _download_artifact_data functions. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

home-assistant · 2026-01-20T14:39:45Z

Hey there @home-assistant/frontend, mind taking a look at this pull request as it has been labeled with an integration (frontend) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of frontend can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign frontend Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) on the pull request.

home-assistant · 2026-01-20T14:39:45Z

Hey there @home-assistant/core, mind taking a look at this pull request as it has been labeled with an integration (backup) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of backup can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign backup Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) on the pull request.

Replace sync PyGithub with aiogithubapi and requests with aiohttp. - Use aiogithubapi.GitHubAPI for GitHub API calls - Use aiohttp_client.async_get_clientsession for HTTP downloads - Remove executor job calls for API operations (now fully async) - Keep executor jobs only for blocking I/O (file operations, zip extraction) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Use specific aiogithubapi exception types instead of checking status attribute - Handle GitHubAuthenticationException for 401 errors - Handle GitHubRatelimitException and GitHubPermissionException for 403 errors - Handle GitHubNotFoundException for 404 errors - Update tests to use aiogithubapi and aiohttp mocks - Replace PyGithub mocks with GitHubAPI.generic() mocks - Replace requests mocks with aioclient_mock (AiohttpClientMocker) - Add test for GitHub API error handling Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

MartinHjelmare · 2026-01-20T18:45:40Z

Why isn't it enough to checkout the frontend PR and use the development_repo option before starting core?

wendevlin · 2026-01-20T18:49:51Z

Why isn't it enough to checkout the frontend PR and use the development_repo option before starting core?

This should be an option for HAOS instances. For example the product team can easily test changes without the need to setup a dev env.

MartinHjelmare · 2026-01-20T18:55:20Z

Please add this context to the PR description.

emontnemery

Looks pretty good.

Some comments.
I've not reviewed the tests.

- Added validation for GitHub token requirement when development PR is set. - Refactored frontend configuration schema to include validation. - Improved test coverage for PR download scenarios, ensuring proper handling of GitHub token absence and cache usage.

…improve error handling for PR downloads

…iles

…-download

emontnemery

Looks good!

emontnemery · 2026-01-28T07:35:10Z

+    def cache_path(self, *path: str) -> str:
+        """Generate path to the file within the cache directory.
+
+        The cache directory is used for temporary data that can be
+        regenerated and is not included in backups.
+
+        Async friendly.
+        """
+        return self.path(".cache", *path)


Let's add some tests of this method, it's fine to just duplicate the tests for the path method above:

core/tests/test_core_config.py

Lines 869 to 883 in 9c07550

async def test_config_path_with_file() -> None:

"""Test get_config_path method."""

hass = Mock()

hass.data = {}

config = Config(hass, "/test/ha-config")

assert config.path("test.conf") == "/test/ha-config/test.conf"

async def test_config_path_with_dir_and_file() -> None:

"""Test get_config_path method."""

hass = Mock()

hass.data = {}

config = Config(hass, "/test/ha-config")

assert config.path("dir", "test.conf") == "/test/ha-config/dir/test.conf"

emontnemery · 2026-01-28T07:36:31Z

 requires-python = ">=3.13.2"
 dependencies = [
  "aiodns==4.0.0",
+  "aiogithubapi==24.6.0",


Suggested change

"aiogithubapi==24.6.0",

# aiogithubapi is needed by frontend

"aiogithubapi==24.6.0",

Please explain why it's needed by frontend and can't be set as a manifest requirement.

As far as I understand it: we import pr_download top level in frontend and pr_download imports aiogithubapi. This happens before manifest requirements are installed and so aiogithubapi wouldn't be available in pr_download. I initially loaded pr_download lazy in the setup but @emontnemery asked me to import it globally.

What's special about the frontend integration in this regard? Other integrations can import 3rd party libraries top level if they specify them in the integration manifest requirements.

frontend is a stage 0 integration in bootstrap.py, so it's loaded before setup.py installs req from manifest. A regular integration is loaded after setup.py did this installations.

If it's the wrong way of doing it please tell me how I should implement it.

When I remove aiogithubapi from pyproject, it removes it from requirements.txt. When I now start it with just requirements.txt installed it crashes. I think this is how HA works: base req are installed from requirements.txt and all in requirements_all.txt is installed on demand. But this on demand happens after frontend setups.

The crash:

Traceback (most recent call last): File "/home/wendelin/ohf/home-assistant/core/.venv/bin/hass", line 10, in <module> sys.exit(main()) ~~~~^^ File "/home/wendelin/ohf/home-assistant/core/homeassistant/__main__.py", line 188, in main from . import config, runner # noqa: PLC0415 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/wendelin/ohf/home-assistant/core/homeassistant/runner.py", line 27, in <module> from . import bootstrap File "/home/wendelin/ohf/home-assistant/core/homeassistant/bootstrap.py", line 41, in <module> from .components import ( ...<22 lines>... ) File "/home/wendelin/ohf/home-assistant/core/homeassistant/components/config/__init__.py", line 5, in <module> from homeassistant.components import frontend File "/home/wendelin/ohf/home-assistant/core/homeassistant/components/frontend/__init__.py", line 40, in <module> from .pr_download import download_pr_artifact File "/home/wendelin/ohf/home-assistant/core/homeassistant/components/frontend/pr_download.py", line 11, in <module> from aiogithubapi import ( ...<6 lines>... ) ModuleNotFoundError: No module named 'aiogithubapi'

I had the issue only in the CI, because on my system I have all req from tests. Erik told me then to add it to pyproject.toml to automatically add it to requirements.txt.

I don't think there is another way of adding it.

It's not a problem with setup or on demand installation requirements. It's a problem with imports and the weird way we have set dependencies in frontend at the moment. Bootstrap pre-imports integrations that frontend has set as dependencies as a performance optimization, but then those integrations import from frontend. Normally that's totally incorrect.

I'll look at this separately, later.

Okay so you'll come back when you have a solution? Or can we merge this and fix this import problem in a separate PR?

We can address that separately. I'm not sure how easy it is. Let's keep it like this here for now.

First of all, the reason why frontend has integrations in its dependencies which it doesn't depend on is to ensure non-optional HTTP/WS endpoints are available when the webserver is started. Relevant PR is #139199 which removed the backup integration from frontend's dependencies and also has a not yet implemented proposal for how we can remove some/most of the other dependencies:

Going forward, we should add a way for frontend to check which integrations will be setup and a way for it to wait for an integration to set up.

In this PR it's a different problem, we're now adding a new library requirement to frontend itself. Specifying the github API in frontend's manifest.json doesn't break core startup, that still works fine without any issue (provided that the aiogithubapi is installed).

What does NOT work fine however is calculating and validating the dependencies.

Without aiogithubapi installed, this is the output from the "Prepare dependencies" CI-job:

Traceback (most recent call last): File "<frozen runpy>", line 198, in _run_module_as_main File "<frozen runpy>", line 88, in _run_code File "/home/runner/work/core/core/script/gen_requirements_all.py", line 649, in <module> sys.exit(main(_VAL, _CI)) ~~~~^^^^^^^^^^^ File "/home/runner/work/core/core/script/gen_requirements_all.py", line 581, in main data = gather_modules() File "/home/runner/work/core/core/script/gen_requirements_all.py", line 346, in gather_modules gather_requirements_from_modules(errors, reqs) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^ File "/home/runner/work/core/core/script/gen_requirements_all.py", line 399, in gather_requirements_from_modules explore_module("homeassistant.scripts", True) ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/runner/work/core/core/script/gen_requirements_all.py", line 260, in explore_module module = importlib.import_module(package) File "/opt/hostedtoolcache/Python/3.13.11/x64/lib/python3.13/importlib/__init__.py", line 88, in import_module return _bootstrap._gcd_import(name[level:], package, level) ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "<frozen importlib._bootstrap>", line 1387, in _gcd_import File "<frozen importlib._bootstrap>", line 1360, in _find_and_load File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 935, in _load_unlocked File "<frozen importlib._bootstrap_external>", line 1023, in exec_module File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed File "/home/runner/work/core/core/homeassistant/scripts/__init__.py", line 13, in <module> from homeassistant import runner File "/home/runner/work/core/core/homeassistant/runner.py", line 27, in <module> from . import bootstrap File "/home/runner/work/core/core/homeassistant/bootstrap.py", line 41, in <module> from .components import ( ...<22 lines>... ) File "/home/runner/work/core/core/homeassistant/components/config/__init__.py", line 5, in <module> from homeassistant.components import frontend File "/home/runner/work/core/core/homeassistant/components/frontend/__init__.py", line 40, in <module> from .pr_download import download_pr_artifact File "/home/runner/work/core/core/homeassistant/components/frontend/pr_download.py", line 11, in <module> from aiogithubapi import ( ...<6 lines>... ) ModuleNotFoundError: No module named 'aiogithubapi'

If running the generate requirements script with aiogithubapi available, aiogithubapi is however not promoted from requirements_all.txt to requirements.txt, and there's not a warning from hassfest.

Co-authored-by: Erik Montnemery <erik@montnemery.com>

… into frontend-pr-download

emontnemery

LGTM, thanks @wendevlin 👍

MartinHjelmare · 2026-01-28T08:04:58Z

Shouldn't this be documented in the dev docs since it's aimed for development?

MartinHjelmare · 2026-01-28T08:15:55Z

There are unresolved comments above.

wendevlin · 2026-01-28T09:22:51Z

Shouldn't this be documented in the dev docs since it's aimed for development?

I am not sure where to put it, because it's not to develop features, it is to easier test frontend PRs.
To develop the PR you still need a dev environment.

I think it would make more sense to get into more detail in the integration docs. @MindFreeze what do you think?

MindFreeze · 2026-01-28T09:44:32Z

I would say it's still mostly a development feature as users would have to be on Github to find a PR to test. Suggest to explain it in the dev docs and add a brief mention that it's possible in https://www.home-assistant.io/integrations/frontend/ with a link to the dev docs.

wendevlin · 2026-01-28T12:58:12Z

I added dev docs and updated the user docs to reference to the dev docs.

emontnemery

Let's clarify the comment in pyproject.toml

Co-authored-by: Erik Montnemery <erik@montnemery.com>

emontnemery · 2026-02-03T09:22:31Z

I discussed this a bit with @MartinHjelmare on Discord, he has no further objections which blocks this PR so I'll go ahead and merge it.

wendevlin and others added 2 commits January 20, 2026 15:23

Refactor error handling in frontend PR download

07de504

Use dictionary mapping for HTTP error messages to eliminate code duplication. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Eliminate duplicate error messages in PR download

689415d

Move GitHub error messages to module-level constants to avoid duplication across _get_pr_head_sha and _download_artifact_data functions. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

home-assistant Bot added cla-signed core has-tests integration: backup integration: frontend by-code-owner Quality Scale: internal labels Jan 20, 2026

wendevlin mentioned this pull request Jan 20, 2026

frontend integration: Add support for development pull request and GitHub token home-assistant/home-assistant.io#43184

Merged

8 tasks

wendevlin changed the title ~~Frontend development PR~~ Frontend integration: add option to use frontend PR artifact Jan 20, 2026

wendevlin mentioned this pull request Jan 20, 2026

Add .cache to backup exclusion list home-assistant/supervisor#6483

Merged

14 tasks

wendevlin changed the title ~~Frontend integration: add option to use frontend PR artifact~~ Add option to use frontend PR artifact to frontend integration Jan 20, 2026

wendevlin and others added 2 commits January 20, 2026 17:43

MindFreeze added the new-feature label Jan 21, 2026

wendevlin added 5 commits January 21, 2026 08:20

Reorganize import of download_pr_artifact for frontend setup

7bba6f0

Update PR_CACHE_DIR to use 'frontend_development_artifacts'

2cf406f

fix backup exclude

900c2f8

Fix tests

20d14a6

Add async-timeout exception for frontend githubapi

698412a

emontnemery reviewed Jan 21, 2026

View reviewed changes

wendevlin added 2 commits January 22, 2026 14:06

Add tests for development PR setup with GitHub token validation

57c324b

wendevlin added 4 commits January 27, 2026 10:36

Refactor frontend configuration validation and update related tests; …

1434fdc

…improve error handling for PR downloads

Remove frontend exception for aiogithubapi from forbidden package list

854637e

Add mock_github_api parameter to test_pr_download_zip_bomb_too_many_f…

a5c2ec4

…iles

Add tests for handling errors during PR download and extraction

17f9137

wendevlin requested a review from emontnemery January 27, 2026 13:15

Merge branch 'dev' of github.com:home-assistant/core into frontend-pr…

b116f93

…-download

emontnemery reviewed Jan 28, 2026

View reviewed changes

wendevlin and others added 3 commits January 28, 2026 08:41

Update pyproject.toml

40914a9

Co-authored-by: Erik Montnemery <erik@montnemery.com>

Add tests for cache_path method in Config class

e9a2648

Merge branch 'frontend-pr-download' of github.com:home-assistant/core…

61a2238

… into frontend-pr-download

emontnemery approved these changes Jan 28, 2026

View reviewed changes

emontnemery added the noteworthy Marks a PR as noteworthy and should be in the release notes (in case it normally would not appear) label Jan 28, 2026

MartinHjelmare marked this pull request as draft January 28, 2026 08:02

wendevlin marked this pull request as ready for review January 28, 2026 08:54

wendevlin marked this pull request as draft January 28, 2026 09:23

wendevlin mentioned this pull request Jan 28, 2026

Add documentation for testing frontend PRs with GitHub artifacts home-assistant/developers.home-assistant#2938

Merged

7 tasks

wendevlin marked this pull request as ready for review January 28, 2026 12:57

MartinHjelmare marked this pull request as draft January 28, 2026 23:09

MartinHjelmare marked this pull request as ready for review February 2, 2026 10:50

emontnemery reviewed Feb 3, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

Update pyproject.toml

2486004

Co-authored-by: Erik Montnemery <erik@montnemery.com>

emontnemery merged commit e6a60df into dev Feb 3, 2026
46 checks passed

emontnemery deleted the frontend-pr-download branch February 3, 2026 09:23

github-actions Bot locked and limited conversation to collaborators Feb 4, 2026

	async def test_config_path_with_file() -> None:
	"""Test get_config_path method."""
	hass = Mock()
	hass.data = {}
	config = Config(hass, "/test/ha-config")
	assert config.path("test.conf") == "/test/ha-config/test.conf"


	async def test_config_path_with_dir_and_file() -> None:
	"""Test get_config_path method."""
	hass = Mock()
	hass.data = {}
	config = Config(hass, "/test/ha-config")
	assert config.path("dir", "test.conf") == "/test/ha-config/dir/test.conf"

	"aiogithubapi==24.6.0",
	# aiogithubapi is needed by frontend
	"aiogithubapi==24.6.0",

Uh oh!

Conversation

wendevlin commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Additional information

Checklist

Uh oh!

home-assistant Bot commented Jan 20, 2026

Uh oh!

home-assistant Bot commented Jan 20, 2026

Uh oh!

MartinHjelmare commented Jan 20, 2026

Uh oh!

wendevlin commented Jan 20, 2026

Uh oh!

MartinHjelmare commented Jan 20, 2026

Uh oh!

emontnemery left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

emontnemery left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wendevlin Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emontnemery Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emontnemery left a comment

Choose a reason for hiding this comment

Uh oh!

MartinHjelmare commented Jan 28, 2026

Uh oh!

MartinHjelmare commented Jan 28, 2026

Uh oh!

wendevlin commented Jan 28, 2026

Uh oh!

MindFreeze commented Jan 28, 2026

Uh oh!

wendevlin commented Jan 28, 2026

Uh oh!

emontnemery left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

emontnemery commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

wendevlin commented Jan 20, 2026 •

edited

Loading

wendevlin Jan 30, 2026 •

edited

Loading

emontnemery Feb 3, 2026 •

edited

Loading