From 5428ed1aa49e63fc01f15b74e948be974ef4231e Mon Sep 17 00:00:00 2001 From: Stefan Agner Date: Mon, 11 May 2026 10:47:47 +0200 Subject: [PATCH] Deprecate legacy "homeassistant" entry in hassio backup/restore folders The hassio.backup_partial and hassio.restore_partial actions still accept "homeassistant" inside the folders list as an alias for setting homeassistant=True. Raise a fixable, persistent repair issue when the legacy alias is used so users can migrate their automations and scripts. The alias is scheduled to be removed in 2026.12. Co-Authored-By: Claude Opus 4.7 (1M context) --- homeassistant/components/hassio/const.py | 1 + homeassistant/components/hassio/repairs.py | 9 ++++++++- homeassistant/components/hassio/services.py | 20 +++++++++++++++++--- homeassistant/components/hassio/strings.json | 11 +++++++++++ tests/components/hassio/test_init.py | 5 +++++ 5 files changed, 42 insertions(+), 4 deletions(-) diff --git a/homeassistant/components/hassio/const.py b/homeassistant/components/hassio/const.py index 6978b545766eb9..77783dbb1ac972 100644 --- a/homeassistant/components/hassio/const.py +++ b/homeassistant/components/hassio/const.py @@ -162,6 +162,7 @@ ISSUE_KEY_SYSTEM_FREE_SPACE = "issue_system_free_space" ISSUE_KEY_ADDON_DEPRECATED = "issue_addon_deprecated_addon" ISSUE_KEY_ADDON_DEPRECATED_ARCH = "issue_addon_deprecated_arch_addon" +ISSUE_KEY_LEGACY_HOMEASSISTANT_FOLDER = "legacy_homeassistant_folder" ISSUE_MOUNT_MOUNT_FAILED = "issue_mount_mount_failed" diff --git a/homeassistant/components/hassio/repairs.py b/homeassistant/components/hassio/repairs.py index d199678acee350..fdb0dd45829b5b 100644 --- a/homeassistant/components/hassio/repairs.py +++ b/homeassistant/components/hassio/repairs.py @@ -8,7 +8,11 @@ from aiohasupervisor.models import ContextType import voluptuous as vol -from homeassistant.components.repairs import RepairsFlow, RepairsFlowResult +from homeassistant.components.repairs import ( + ConfirmRepairFlow, + RepairsFlow, + RepairsFlowResult, +) from homeassistant.const import ATTR_NAME from homeassistant.core import HomeAssistant @@ -21,6 +25,7 @@ ISSUE_KEY_ADDON_DEPRECATED_ARCH, ISSUE_KEY_ADDON_DETACHED_ADDON_REMOVED, ISSUE_KEY_ADDON_PWNED, + ISSUE_KEY_LEGACY_HOMEASSISTANT_FOLDER, ISSUE_KEY_SYSTEM_DOCKER_CONFIG, PLACEHOLDER_KEY_ADDON, PLACEHOLDER_KEY_ADDON_DOCUMENTATION, @@ -226,6 +231,8 @@ async def async_create_fix_flow( data: dict[str, str | int | float | None] | None, ) -> RepairsFlow: """Create flow.""" + if issue_id == ISSUE_KEY_LEGACY_HOMEASSISTANT_FOLDER: + return ConfirmRepairFlow() supervisor_issues = get_issues_info(hass) issue = supervisor_issues and supervisor_issues.get_issue(issue_id) if issue and issue.key == ISSUE_KEY_SYSTEM_DOCKER_CONFIG: diff --git a/homeassistant/components/hassio/services.py b/homeassistant/components/hassio/services.py index 8b6030eb86f46b..155c0b8006841c 100644 --- a/homeassistant/components/hassio/services.py +++ b/homeassistant/components/hassio/services.py @@ -28,6 +28,7 @@ from homeassistant.helpers import ( config_validation as cv, device_registry as dr, + issue_registry as ir, selector, ) from homeassistant.helpers.service import async_register_admin_service @@ -47,6 +48,7 @@ ATTR_PASSWORD, ATTR_SLUG, DOMAIN, + ISSUE_KEY_LEGACY_HOMEASSISTANT_FOLDER, MAIN_COORDINATOR, SupervisorEntityModel, ) @@ -76,7 +78,9 @@ LEGACY_FOLDER_HOMEASSISTANT = "homeassistant" -def _normalize_partial_options_data(data: dict[str, Any]) -> dict[str, Any]: +def _normalize_partial_options_data( + hass: HomeAssistant, data: dict[str, Any] +) -> dict[str, Any]: """Map legacy aliases used by both partial backup and partial restore handlers.""" if ATTR_APPS in data: data[ATTR_ADDONS] = data.pop(ATTR_APPS) @@ -90,6 +94,16 @@ def _normalize_partial_options_data(data: dict[str, Any]) -> dict[str, Any]: f"{LEGACY_FOLDER_HOMEASSISTANT!r} entry in {ATTR_FOLDERS}" ) data[ATTR_HOMEASSISTANT] = True + ir.async_create_issue( + hass, + DOMAIN, + ISSUE_KEY_LEGACY_HOMEASSISTANT_FOLDER, + breaks_in_ha_version="2026.12.0", + is_fixable=True, + is_persistent=True, + severity=ir.IssueSeverity.WARNING, + translation_key=ISSUE_KEY_LEGACY_HOMEASSISTANT_FOLDER, + ) if folders: data[ATTR_FOLDERS] = folders else: @@ -375,7 +389,7 @@ async def async_partial_backup_service_handler( service: ServiceCall, ) -> ServiceResponse: """Handler for create partial backup service. Returns the new backup's ID.""" - data = _normalize_partial_options_data(service.data.copy()) + data = _normalize_partial_options_data(hass, service.data.copy()) options = PartialBackupOptions(**data) try: @@ -422,7 +436,7 @@ async def async_partial_restore_service_handler(service: ServiceCall) -> None: """Handler for partial restore service.""" data = service.data.copy() backup_slug = data.pop(ATTR_SLUG) - data = _normalize_partial_options_data(data) + data = _normalize_partial_options_data(hass, data) options = PartialRestoreOptions(**data) try: diff --git a/homeassistant/components/hassio/strings.json b/homeassistant/components/hassio/strings.json index a0a36a7a4f0d0f..a433213b71a823 100644 --- a/homeassistant/components/hassio/strings.json +++ b/homeassistant/components/hassio/strings.json @@ -203,6 +203,17 @@ }, "title": "Reboot required" }, + "legacy_homeassistant_folder": { + "fix_flow": { + "step": { + "confirm": { + "description": "An automation or script called the `hassio.backup_partial` or `hassio.restore_partial` action with `\"homeassistant\"` listed in `folders`. This is a legacy alias for the `homeassistant: true` option and will stop being accepted in a future release.\n\nUpdate the affected automations and scripts to set `homeassistant: true` and remove `\"homeassistant\"` from the `folders` list. When this is done, select **Submit** to mark this issue as resolved.", + "title": "Legacy \"homeassistant\" folder used in partial backup/restore" + } + } + }, + "title": "Legacy \"homeassistant\" folder used in partial backup/restore" + }, "unhealthy": { "description": "System is currently unhealthy due to {reason}. For troubleshooting information, select Learn more.", "title": "Unhealthy system - {reason}" diff --git a/tests/components/hassio/test_init.py b/tests/components/hassio/test_init.py index f9762c7082b021..ca5637ccc27a7f 100644 --- a/tests/components/hassio/test_init.py +++ b/tests/components/hassio/test_init.py @@ -797,6 +797,11 @@ async def test_partial_backup_legacy_homeassistant_folder( folders={Folder.SSL}, ) ) + issue_registry = ir.async_get(hass) + assert ( + issue_registry.async_get_issue("hassio", "legacy_homeassistant_folder") + is not None + ) @pytest.mark.usefixtures("hassio_env")