Deprecate legacy "homeassistant" entry in hassio backup/restore folders

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"
 

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:

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:

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}"

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")