VNOX-Client/docs/release.md

185 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Релизы и 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 с лейблом `self-hosted` (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:
```sh
./act_runner register --no-interactive \
--instance https://git.wihuk.pro \
--token <REGISTRATION_TOKEN> \
--name vnox-runner-1 \
--labels "self-hosted: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 и поставьте тег:
```sh
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`.
Поля манифеста:
```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):
```sh
scripts/release/manifest.py verify --manifest manifest.json \
--sig manifest.json.sig --public-key <PUBLIC_KEY_B64>
```
## Генерация и ротация ключа
Первичная генерация:
```sh
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.
## Раннер
Workflow используют метку `self-hosted` (раннер `pink-star-ci`, режим хоста). На хосте должны быть: Rust stable ≥ 1.94 (или rustup), Node.js для `actions/*`, и пакеты из шага «Install system dependencies» (apt пропускается, если нет root/sudo без пароля).
### Риски self-hosted раннера
Раннер работает на хосте без изоляции, поэтому: CI пропускает PR из форков; в настройках репозитория отключите workflow для форков и требуйте одобрения для первых участников; раннер не должен работать от root; секреты лежат только в репозитории и доступны лишь job `publish`. Лучшее решение — отдельные метки (`ci-ephemeral` для CI и `release-signing` для публикации) и контейнерный раннер для CI, когда появится второй хост.