merge: gitea CI and release pipeline
This commit is contained in:
commit
7b691bed2a
6 changed files with 724 additions and 0 deletions
187
docs/release.md
Normal file
187
docs/release.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# Релизы и 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, когда появится второй хост.
|
||||
|
||||
Сборка релиза использует одноразовые `CARGO_HOME`/`RUSTUP_HOME` в `$RUNNER_TEMP` (тулчейн ставится с нуля, постоянные настройки хоста игнорируются); подпись запускается как `python3 -I`; при отсутствии зависимостей job падает, а не продолжается. Остаточный риск: одна машина и для CI, и для подписи. Для полной изоляции нужны отдельные раннеры с метками `ci-untrusted` и `release-signing`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue