185 lines
12 KiB
Markdown
185 lines
12 KiB
Markdown
# Релизы и 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, когда появится второй хост.
|