chore: update .gitignore, remove Dockerfile, and enhance documentation

- Added .release-version, CHANGELOG.md, and deploy/docker/docker-bake.override.hcl to .gitignore. - Removed Dockerfile as part of the cleanup. - Updated AGENTS.md and README.md to include new documentation on CI/Docker processes and deployment instructions. - Enhanced package.json with new devDependencies for commit linting and semantic release. - Updated pnpm-lock.yaml to reflect new dependencies and versions. These changes streamline the project structure and improve documentation clarity.
2026-08-19 00:02:33 +07:00
parent 9121cbe842
commit 4fedf83078
28 changed files with 5636 additions and 162 deletions
@@ -0,0 +1,80 @@
+# Gitea Actions
+
+| Workflow | Когда | Что |
+|----------|--------|-----|
+| [workflows/ci.yaml](workflows/ci.yaml) | pull request в main/master | quality gates + commitlint |
+| [workflows/cd.yaml](workflows/cd.yaml) | push в main/master | quality gates + semantic-release + docker push |
+| [workflows/quality.yaml](workflows/quality.yaml) | reusable (`workflow_call`) | changes, openapi, web, api, commitlint, docker-check |
+
+Подробнее: [docs/releasing.md](../docs/releasing.md).
+
+## CI (quality gates)
+
+Job **changes** вычисляет флаги по путям в diff. Полный прогон: `.gitea/workflows/*`, `scripts/*`, корневой `package.json` / `pnpm-lock.yaml` / `.releaserc.json`. Правки `.cursor/`, `.claude/`, `*.md` (кроме `docs/openapi.yaml`) quality jobs не запускают.
+
+На **pull request** — **commitlint**. При изменении `deploy/docker/**` / `.dockerignore` — job **docker-check** (`bake --print`, bake без `--push` если есть доступ к registry).
+
+Кэш зависимостей — нативный `actions/cache` (cache server act_runner), ключ `sha256sum` lockfile (не `hashFiles`). Пути **абсолютные** (`$HOME/.pnpm-store`): тильда `~` на Gitea часто не раскрывается и даёт вечный miss.
+
+Кэшируется целиком: pnpm store + `node_modules` + corepack. При hit: `pnpm install --offline`.
+
+Если restore пишет `connect ECONNREFUSED` / `cache server not configured` — на runner включите cache server (см. ниже). Иначе каждый job снова качает пакеты (~минуты).
+
+Runner: `ubuntu-latest`, Docker для **docker-check** (PR) и **publish** (CD).
+
+## CD (job publish)
+
+После успешных quality gates на **push в main** job **publish**:
+
+1. `pnpm exec semantic-release` — тег `vX.Y.Z` на **текущий commit** (без дополнительного commit в main).
+2. Gitea Release + `CHANGELOG.md` как attachment (не в git).
+3. Зеркало base-образов в `evofw-buildcache:base-*` (`deploy/docker/mirror-base-images.sh`; skip существующих тегов, `linux/amd64`, retry при 429).
+4. `docker buildx bake default --push` с `VERSION=X.Y.Z`, `pull=false`, named builder `evofw` (`cleanup: false`).
+
+Если releasable-коммитов нет — semantic-release no-op, образы не публикуются.
+
+Повтор упавшего **publish** (тег уже есть, bake нет): detect берёт `v*` на `HEAD` и всё равно пушит образы. Подробнее: [docs/releasing.md](../docs/releasing.md#перезапуск-упавшего-job-publish).
+
+### Секреты
+
+**`ACTIONS_PAT`**: push tags, releases, Container Registry. Для git tag fallback: `github.token`. Push OCI — **только PAT** (у `GITEA_TOKEN` нет права packages).
+
+### Теги образов
+
+```text
+git.shx.one/<owner>/evofw:latest
+git.shx.one/<owner>/evofw:v1.2.3
+git.shx.one/<owner>/evofw:1.2.3
+git.shx.one/<owner>/evofw:<short-sha>
+git.shx.one/<owner>/evofw:sha-<full-sha>
+```
+
+Тот же манифест публикуется как `evofirewall` (drop-in для старого compose).
+
+Кэш сборки: `evofw-buildcache:node-buildcache` и `evofw-buildcache:base-*`.
+
+Пример:
+
+```bash
+docker pull git.shx.one/denozord/evofw:1.2.3
+```
+
+См. [deploy/docker/README.md](../deploy/docker/README.md).
+
+## act_runner: cache server
+
+`actions/cache` ходит в **встроенный cache server** runner (не GitHub `type=gha`). Кэш локален для этого runner.
+
+В `config.yaml` runner:
+
+```yaml
+cache:
+  enabled: true
+  dir: ""          # по умолчанию $HOME/.cache/actcache
+  host: ""         # IP, доступный из job-контейнера (не 0.0.0.0)
+  port: 8088
+```
+
+Если runner в Docker, а jobs — отдельные контейнеры: пробросьте порт и задайте `host` (LAN IP хоста) или `external_server: "http://<host>:8088/"`. Иначе restore — timeout/ECONNREFUSED и пакеты качаются снова.
+
+Не делайте `docker system prune -a` по cron: сотрётся и Docker-кэш FROM, и пользы от `cleanup: false` у buildx не будет.