Апгрейды и self-update

Обновить сам gtcnsl

# доступен ли новый релиз? (без записи, --yes не нужен)
gtcnsl self-update --dry-run

# обновиться до последнего релиза
gtcnsl self-update --yes

# зафиксировать конкретную версию
gtcnsl self-update --to v0.6.1 --yes

Под капотом он определяет последний тег по versions.json, скачивает https://dl.gtcnsl.ru/<tag>/gtcnsl-<tag>-linux-<arch>, сверяет с checksums.txt (SHA-256), снапшотит работающий бинарник, атомарно меняет его, затем запускает gtcnsl --version для подтверждения — откатываясь автоматически, если проверка не прошла.

Откатить gtcnsl

gtcnsl self-update --rollback --yes

Восстанавливает бинарник, заменённый последним self-update. (--rollback нельзя сочетать с --to или --dry-run.)

Двигать Gitea вперёд

gtcnsl gitea upgrade [--to <v>] [--yes] — короткая команда для уже установленной Gitea: она чисто отказывает, если ставить пока нечего, а иначе едет по тому же пути обновления на месте, что и gitea install --to <version> всегда использовала: пути берутся из живой установки (обновление никогда не переносит данные), --data-dir/--log-dir, противоречащие живой установке, отклоняются, а юнит gitea.service, написанный не gtcnsl, сохраняется байт-в-байт — только замена бинарника и перезапуск; передайте --rewrite-unit, если сознательно хотите шаблон gtcnsl. Если в том же шаге нужны дополнительные флаги — обращайтесь напрямую к gitea install --to. TUI показывает ту же детекцию баннером обновления с живыми путями в полях.

Если после замены бинарника что-то ломается — деплой юнита, рестарт или health-check после апгрейда — gtcnsl автоматически восстанавливает предыдущий бинарник Gitea и перезапускает сервис; после неудачного апгрейда хост никогда не остаётся без работающей Gitea.

Данные Gitea сохраняются при замене бинарника, но сначала сделайте снапшот, чтобы можно было вернуться в заведомо рабочее состояние:

gtcnsl backup
gtcnsl gitea upgrade --to v1.27.0 --yes
gtcnsl doctor   # убедиться, что юнит поднялся и здоров

gtcnsl backup снапшотит бинарник Gitea, app.ini, secrets.ini, дерево custom/, а также — если установлен раннер — его регистрацию .runner, config.yaml и юнит gitea-runner.service, всё в /var/lib/gtcnsl/backups/<id>/. Список и восстановление:

gtcnsl backup list
gtcnsl restore <backup-id> --yes

restore снапшотит живые файлы, останавливает Gitea (и раннер, если в бэкапе есть его состояние), подставляет бэкап, рестартит и проверяет здоровье — отменяя себя, если Gitea не поднимается. Бэкап, сделанный до этого релиза, восстанавливается точно так же, как раньше — просто без пунктов раннера, которых в нём нет.

Смена мажорной версии — только с вашего согласия

Любое обновление, которое выполняет gtcnsl, — gitea upgrade, runner upgrade, self-update и install поверх существующей установки — остаётся внутри мажорной версии, которая у вас уже стоит, пока вы не решите иначе. Мажор — это первое число: длинная серия Gitea 1.x — один мажор, а с 28.0.0 (апстрим убрал префикс 1.) каждый фичевый релиз Gitea — 28, 29, … — отдельный мажор; у раннера мажоры — 3, 4, ….

• Без --to вы получаете новейший релиз своего мажора: Gitea на 1.26 или 1.27 переходит на новейшую 1.27.x, раннер на 3.x — на новейшую 3.x. Если вышел мажор новее, gtcnsl предупреждает и называет его. Свежая установка без --to получает новейший мажор, проверенный этим релизом gtcnsl.
• --to в мажор новее — отдельное решение. В терминале gtcnsl называет обе версии и просит подтвердить; в cron или CI передайте --allow-major-upgrade. --yes не считается согласием на смену мажора — без согласия gtcnsl отказывает, ничего не изменив.

# остаётся в вашем мажоре, предупреждает, если вышел новый
gtcnsl gitea upgrade --yes

# переход на новый мажор без терминала
gtcnsl backup
gtcnsl gitea upgrade --to v28.0.0 --yes --allow-major-upgrade

Двигать раннер вперёд

gtcnsl runner upgrade [--to <v>] [--yes] — аналог gitea upgrade для раннера: чисто отказывает, если раннер не установлен, иначе меняет бинарник на месте и перезапускает сервис. Команда следует фактам живого юнита — путь к бинарнику, рабочая директория, даже устаревшее имя act_runner.service из времён до переименования в v0.2 — вместо того чтобы полагаться на канонический layout gtcnsl, так что усыновлённый или перенесённый раннер (gtcnsl runner adopt) тоже обновляется корректно. Как и gitea upgrade, при неудачной замене gtcnsl автоматически восстанавливает предыдущий бинарник раннера и перезапускает сервис.

gtcnsl runner upgrade --yes

[!NOTE] Переход на Runner 3.x Механику 3.x (новый лок «один процесс на .runner», генерацию конфига) gtcnsl берёт на себя, но три изменения апстрима живут внутри ваших workflow, а не в gtcnsl:

• Кэш и артефакты: штатные actions/upload-artifact, download-artifact и actions/cache теперь работают как есть — форк gitea-upload-artifact можно убрать. Cache service v2 включён по умолчанию (cache.v2: false в config.yaml, чтобы выключить).
• container.options, дотягивающиеся до хоста (--pid, --cap-add, устройства, …), молча вырезаются, пока в config.yaml не включён container.privileged.
• ::set-env:: / ::add-path:: (раннер ≥ 3.1.0) отклоняются, если шаг или джоба не задаёт ACTIONS_ALLOW_UNSECURE_COMMANDS.

[!NOTE] Переход на Runner 4.x Runner 4 — смена мажора (--to v4.1.0, с согласием). Сам раннер gtcnsl берёт на себя; эти изменения апстрима после 3.1 касаются ваших workflow и config.yaml:

• Кэш через раннер (4.0): джобы ходят в кэш через свой раннер. Джобы с container.network: bridge до него больше не достают — оставьте container.network пустым или используйте пользовательскую сеть; при удалённом DOCKER_HOST нужны cache.host/cache.port.
• valid_volumes (4.0): * больше не совпадает через / — пишите /data/** вместо /data/*.
• Tool cache не общий (3.2): каждая джоба видит только то, что есть в её образе; для прежнего общего тома задайте runner.tool_cache_mode: shared.
• Ограничения container.options (3.3.1): workflow больше не может передавать --env-file, --label-file и опции драйвера томов, а голый --env NAME не читает окружение раннера.
• NODE_OPTIONS (3.3.2) из workflow больше не задаётся.

Дальше

Если после апгрейда что-то не так — начните с «Решение проблем и FAQ».