VNOX-Client/docs/release.md
loki5512344 948d10bd37
ci: add gitea workflows and signed release pipeline
CI runs fmt, clippy and tests. Tag releases build Linux and Windows (mingw cross) artifacts, SHA256SUMS and an Ed25519 signed manifest, then publish via the Gitea API. Helper scripts live in scripts/release, docs in docs/release.md.
2026-11-01 15:48:56 +01:00

10 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.