fgl-aircon/docs/RELEASE_HA.md

Релиз и установка HA-интеграции

1. Внутренняя сборка и установка (Gitea, текущий режим)

Внутренний репозиторий — Gitea (git.ratigorsk-12.ru), поэтому:

• HACS к Gitea не подключается (только публичный GitHub) — для внутреннего использования интеграция ставится копированием custom_components/fglair/ в <config>/custom_components/;
• зависимость pyfglair публикуется в PyPI-реестр пакетов Gitea и ставится оттуда.

1.1. Сборка и публикация wheel (Gitea Actions, ручной запуск)

Workflow: .gitea/workflows/publish-pyfglair.yaml (workflow объявляет permissions: contents: read, packages: write).

Авторизация — любой из вариантов:

• Встроенный job-токен (Gitea ≥ 1.27, где packages поддержан у features): ничего настраивать не нужно, workflow возьмёт ${{ secrets.GITEA_TOKEN }};
• Personal access token со scope write:package (для версий, где публикация пакетов job-токеном ещё не реализована — см. HACS-док Gitea «Package repository authorization»): положите его в секрет PYPI_TOKEN, при необходимости задайте PYPI_USER (имя пользователя к PAT; иначе — актор запуска). Имена секретов не могут начинаться с GITEA_ — префикс зарезервирован Gitea.

Запуск: Actions → Publish pyfglair → Run workflow (вход bundled_mbedtls: 1 — встроить mbedtls, 0 — системный libmbedtls-dev). Артефакт появится в https://git.ratigorsk-12.ru/api/packages/<owner>/pypi/simple/pyfglair/ (<owner> — владелец репозитория, напр. esphome).

Workflow собирает wheel + sdist, прогоняет smoke-тест установки (запускается из /tmp с python -P, чтобы не подхватить исходники pyfglair/ вместо wheel) и публикует через twine upload --skip-existing. Повторная публикация той же версии пропускается; для новой версии поднимите version в pyproject.toml.

1.2. Установка pyfglair в Home Assistant

Пакет обязателен (cffi-биндинги). Варианты:

• Вручную в окружение HA (проще всего для теста; HA увидит установленный дистрибутив и не будет вызывать pip для pyfglair>=1.0.0):

  # в контейнере/venv Home Assistant (Advanced SSH & Web Terminal, docker exec и т.п.)
  pip install --index-url https://<user>:<token>@git.ratigorsk-12.ru/api/packages/<owner>/pypi/simple \
      --no-deps pyfglair
  

• Через индекс pip в окружении HA (pip.conf/PIP_EXTRA_INDEX_URL): тогда HA сам поставит pyfglair из манифеста. Учтите риск dependency confusion при --extra-index-url — для внутреннего стенда допустимо.

• Публичный PyPI — см. §2 (для распространения вне сети).

1.3. Обновление интеграции

custom_components/fglair/ обновляется из Gitea (git pull / копирование), затем перезапуск HA. pyfglair — переустановкой из пакетов Gitea.

2. Публикация pyfglair на PyPI (если понадобится публично)

PyPI (warehouse) принимает только manylinux*/musllinux* теги, поэтому локальный py3-none-linux_x86_64 нужно чинить auditwheel'ом в контейнере со старой glibc:

pip install build auditwheel twine

# для каждой архитектуры (linux x86_64/aarch64) в manylinux-контейнере:
python -m build --wheel
auditwheel repair dist/pyfglair-*.whl --plat manylinux2014_x86_64 -w dist/manylinux/
rm -f dist/pyfglair-*-linux_*.whl
python -m build --sdist
twine upload dist/manylinux/* dist/*.tar.gz

Проверки: scripts/py-ci.sh, scripts/ci.sh, readelf -d по .so (нет внешней libmbedcrypto), установка wheel в чистый venv.

3. GitHub-зеркало и Custom Repositories (HACS)

HACS устанавливает интеграции только с публичных GitHub-репозиториев (GitLab/Gitea не поддерживаются: https://hacs.xyz/docs/faq/other_git_providers/). Публикация в default-репозиторий HACS не требуется — достаточно Custom Repositories, но хостинг обязан быть GitHub.

git remote add github git@github.com:<owner>/fgl-aircon.git
git push --mirror github

После зеркала:

• заполнить на GitHub Description, Topics (home-assistant, hacs, fujitsu, air-conditioner), включить Issues (проверяет HACS Action);
• проверить codeowners в manifest (@petr.polezhaev; для GitHub нужен реальный GitHub-логин);
• обновить version манифеста под тег; заменить заглушки screenshots/step-N.png и brand/*.png реальными ассетами;
• создать тег (semver) — HACS покажет версию.

Готовые файлы HACS: hacs.json, info.md, LICENSE (MIT), custom_components/fglair/brand/ (icon/icon@2x/logo + dark-варианты), workflows .github/workflows/{validate-hacs,hassfest}.yaml.

4. Приёмка на живом стенде

• tests/acceptance/test_esphome_ha.py quick — матрица изменений (HA; с --esphome-host шаги «режим/уставка» идут через ESPHome, проверка — по состоянию в HA), возврат к исходному.
• long --hours 24 --interval 3600 --report acceptance.csv.
• Сценарии: 503 (два слота), key_error + Repair, offline/восстановление, два устройства, options flow (копирование/смена ключа), reconfigure.

5. Ограничения стенда

• Реального железа/облака в CI нет: протокол проверен mock-модулем, облако — мок-сервером; приёмочный скрипт имеет self-test на моке HA REST.
• Суточный soak, re-key и облачный вход — только на приборе/аккаунте.
• Gitea Actions: встроенный GITEA_TOKEN не публикует пакеты (нужен PAT); actions/checkout/setup-python тянутся с github.com (для изолированного инстанса используйте абсолютные URL зеркал).