VNOX-Client/docs/release.md

11 KiB
Raw Blame History

Релизы и CI

CI и релизы работают на Gitea Actions. Workflow-файлы лежат в .gitea/workflows/ (каталог .github/workflows не используется).

Файл Когда запускается Что делает
.gitea/workflows/ci.yml push, pull request cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test --workspace
.gitea/workflows/release.yml push тега v* сборка Linux и Windows, подпись манифеста, создание релиза в Gitea

Регистрация act_runner

Нужен хотя бы один runner с лейблом ubuntu-latest (Docker на хосте runner'а обязателен).

  1. В Gitea откройте Site Administration, Actions, Runners (для всего инстанса) либо Settings, Actions, Runners в репозитории или организации, и нажмите Create new runner. Скопируйте registration token.

  2. На хосте runner'а скачайте act_runner с https://gitea.com/gitea/act_runner/releases.

  3. Зарегистрируйте runner:

    ./act_runner register --no-interactive \
      --instance https://git.wihuk.pro \
      --token <REGISTRATION_TOKEN> \
      --name vnox-runner-1 \
      --labels "ubuntu-latest:docker://catthehacker/ubuntu:act-22.04"
    
  4. Запустите демон: ./act_runner daemon (рекомендуется systemd-юнит).

  5. Убедитесь, что в UI runner отображается как Idle.

Замечания:

  • В app.ini Gitea должен быть включён раздел [actions] ENABLED = true, а у репозитория включены Actions (Settings, Repository, Enable Repository Actions).
  • Первая сборка долгая (Slint, GStreamer-биндинги, opus из исходников). Кэш cargo (actions/cache) ускоряет последующие. Для сборки нужно около 8 ГБ RAM и 10 ГБ диска.
  • Workflow ставит зависимости через apt-get; образ catthehacker/ubuntu работает от root, поэтому sudo не нужен (скрипты используют его, только если он есть).
  • Шаги actions/checkout и actions/cache скачиваются с адреса, заданного в [actions] DEFAULT_ACTIONS_URL (по умолчанию GitHub). Если исходящий доступ закрыт, зеркалируйте эти actions в свой Gitea.
  • Для actions/cache нужен cache server act_runner (включён по умолчанию, секция cache в config.yaml). Без него шаг кэша завершается предупреждением, а сборка идёт дальше.

Секреты и переменные

Settings, Actions, Secrets (репозиторий или организация):

Имя Обязателен Описание
VNOX_RELEASE_SIGNING_KEY да Приватный ключ Ed25519: base64 от сырого 32-байтного seed. Без него релиз-джоба падает и ничего не публикует.
RELEASE_TOKEN нет Персональный токен Gitea со scope write:repository. Если не задан, используется встроенный GITHUB_TOKEN. Задайте, если у встроенного токена нет прав на создание релизов.

Settings, Actions, Variables:

Имя Описание
VNOX_MIN_VERSION Необязательно. Минимальная поддерживаемая версия клиента, попадает в manifest.json (min_version). По умолчанию 0.0.0.

Как выпустить релиз

  1. Поднимите version в Cargo.toml (например 0.2.0) и обновите Cargo.lock (cargo check).

  2. В CHANGELOG.md переименуйте раздел [Unreleased] в ## [0.2.0] - ГГГГ-ММ-ДД (формат заголовка: ## [версия]). Текст раздела станет описанием релиза; пустой или отсутствующий раздел останавливает релиз.

  3. Закоммитьте, дождитесь зелёного CI и поставьте тег:

    git tag v0.2.0
    git push origin v0.2.0
    
  4. Workflow release проверит, что:

    • задан секрет VNOX_RELEASE_SIGNING_KEY;
    • версия тега (без v) равна version в Cargo.toml, иначе релиз отклоняется;
    • в CHANGELOG.md есть непустой раздел для этой версии.
  5. Затем он соберёт артефакты, подпишет манифест и создаст релиз в Gitea (сначала как черновик, публикуется после загрузки всех файлов).

Теги с суффиксом (v0.2.0-rc.1) попадают в канал beta и помечаются как pre-release; остальные идут в канал stable.

Артефакты релиза

  • vnox-client-<версия>-linux-x86_64.tar.gz: бинарник vnox-client, LICENSE, README.md;
  • vnox-client-<версия>-windows-x86_64.zip: vnox-client.exe, LICENSE, README.md (кросс-компиляция из Linux, target x86_64-pc-windows-gnu, mingw-w64);
  • SHA256SUMS: хэши архивов (sha256sum -c SHA256SUMS);
  • manifest.json и manifest.json.sig: подписанный манифест для апдейтера.

Windows-сборка не включает screen-capture: его зависимости (zbus, GStreamer) объявлены только для target_os = "linux".

Манифест и подпись

manifest.json записывается в канонической форме: UTF-8, ключи отсортированы, без пробелов, без перевода строки в конце. manifest.json.sig содержит base64 от подписи Ed25519 (64 байта) над точными байтами файла manifest.json.

Поля манифеста:

{
  "schema": 1,
  "product": "vnox-client",
  "version": "0.2.0",
  "channel": "stable",
  "min_version": "0.0.0",
  "published_at": "2026-11-01T14:44:21Z",
  "artifacts": [
    {"platform": "linux-x86_64", "name": "...", "url": "...", "sha256": "...", "size": 123}
  ]
}

Алгоритм проверки в апдейтере:

  1. Скачать manifest.json и manifest.json.sig.
  2. Проверить подпись Ed25519 над сырыми байтами файла вшитым публичным ключом. Только после успеха разбирать JSON.
  3. Сравнить version с текущей, учесть min_version и channel.
  4. Скачать артефакт для своей платформы, проверить size и sha256, и только потом применять.

Публичный ключ нужно вшить в клиент как константу (например, в модуль апдейтера src/update/), в виде 32 сырых байт. scripts/release/keygen.py печатает его и в base64, и в виде готовой Rust-константы RELEASE_PUBLIC_KEY: [u8; 32].

Скрипты scripts/release/

Требуется Python 3 и пакет cryptography (pip install cryptography).

  • keygen.py: генерирует пару ключей; --private-out FILE пишет seed в файл с правами 0600.
  • manifest.py build|sign|verify: сборка, подпись и проверка манифеста.
  • extract_changelog.py VERSION: выводит раздел CHANGELOG.md для версии.

Локальная проверка подписи (публичный ключ в base64):

scripts/release/manifest.py verify --manifest manifest.json \
  --sig manifest.json.sig --public-key <PUBLIC_KEY_B64>

Генерация и ротация ключа

Первичная генерация:

python3 -m pip install cryptography
scripts/release/keygen.py --private-out vnox-release.key
  1. Содержимое vnox-release.key сохраните в секрет VNOX_RELEASE_SIGNING_KEY.
  2. Файл ключа уберите в менеджер паролей или офлайн-хранилище и удалите с рабочей машины. Никогда не коммитьте его.
  3. Публичный ключ (вывод скрипта) вшейте в клиент и выпустите релиз с ним.

Ротация (плановая или при компрометации):

  1. Сгенерируйте новую пару ключей.
  2. Плановая ротация: выпустите релиз, подписанный старым ключом, в который вшиты оба публичных ключа (старый и новый; апдейтер принимает подпись любого из них). Когда большинство пользователей обновилось, замените секрет VNOX_RELEASE_SIGNING_KEY на новый ключ и выпускайте релизы уже им, затем удалите старый публичный ключ из клиента в одном из следующих релизов.
  3. Компрометация: сразу замените секрет, отзовите (удалите) релизы, подписанные скомпрометированным ключом. Клиенты со старым ключом без нового публичного ключа придётся обновлять вручную, поэтому держите в клиенте запасной публичный ключ заранее.
  4. После смены секрета проверьте подпись следующего релиза скриптом manifest.py verify.

Безопасность пайплайна

  • Job build не имеет секретов и не использует кеш; он собирает артефакты и проверяет, что тег стоит на коммите из main.
  • Job publish получает VNOX_RELEASE_SIGNING_KEY и токен только в тех шагах, где они нужны, проверяет SHA256SUMS и подписывает manifest.
  • Рекомендуется включить защищённые теги v* в настройках репозитория Gitea (кто может создавать теги релиза).
  • Gitea 1.22 поддерживает actions/upload-artifact@v3/download-artifact@v3, не v4.