issues/27: docs git-flow prod test stage

2026-05-28 19:19:52 +03:00
parent 0acf59c408
commit 11348a4e35
6 changed files with 318 additions and 27 deletions
@@ -0,0 +1,278 @@
+# Git-flow: ветки, теги и автодеплой
+
+Единый процесс для репозиториев приложений в Gitea:
+
+| Репозиторий Gitea | Локальная папка | CI по тегам |
+|-------------------|-----------------|-------------|
+| `sova/backend` | `sova-backend/` | да |
+| `sova/adminpanel` | `sova-adminpanel/` | да |
+| `sova/cabinet` | `sova-cabinet/` | да |
+| `sova/docs` | `sova-docs/` | да |
+| `sova/sova-mocks` | `sova-mocks/` | нет (Helm chart, ArgoCD sync) |
+
+`sova/sova-deploy` — GitOps-репозиторий: CI пишет в **`main`**, ArgoCD читает `values-{env}.yaml`. Отдельные ветки prod/test/stage для deploy **не нужны**.
+
+---
+
+## Глоссарий веток
+
+| Ветка | Назначение | Откуда создаём feature | Куда мержим задачу |
+|-------|------------|------------------------|-------------------|
+| **`prod`** | Актуальный продакшн-код (бывш. `main`/`master`) | — | После успешного stage-тестирования: **stage → prod** |
+| **`test`** | Test-контур (k3s песочница) | feature от **`prod`** | После code review задачи |
+| **`stage`** | Stage-контур (регресс / нагрузка) | feature от **`prod`** | После успешного test QA |
+
+**Правило:** feature-ветки **всегда** ответвляются от `prod`, не от `test` и не от `stage`.
+
+```mermaid
+gitGraph
+  commit id: "prod baseline"
+  branch test
+  branch stage
+  checkout prod
+  branch feature/TASK-123
+  commit id: "implement"
+  checkout test
+  merge feature/TASK-123 id: "PR → test"
+  checkout feature/TASK-123
+  checkout stage
+  merge feature/TASK-123 id: "PR → stage (NOT test!)"
+  checkout prod
+  merge stage id: "release: stage → prod"
+```
+
+### ⚠️ Частая ошибка
+
+**Нельзя** мержить ветку `test` в `stage`. В `test` могут лежать чужие незавершённые задачи — они «прицепом» уедут на stage.
+
+**Правильно:** мержить **конкретную feature-ветку** (которая прошла test) в `stage`.
+
+---
+
+## Формат тегов (без изменений)
+
+```
+{component}-v{semver}-{env}
+```
+
+| Суффикс `env` | Контур | Пример |
+|---------------|--------|--------|
+| `test` | Test (k3s) | `backend-v1.0.2-test` |
+| `stage` | Stage (будущее) | `backend-v1.0.2-stage` |
+| `prod` | Production (будущее) | `backend-v1.0.2-prod` |
+
+Компоненты: `backend`, `adminpanel`, `cabinet`, `docs`.
+
+Тег создаётся **на ветке с тем же именем**, что и суффикс env:
+
+- тег `backend-v1.0.2-test` → ветка **`test`**
+- тег `backend-v1.0.2-stage` → ветка **`stage`**
+- тег `backend-v1.0.2-prod` → ветка **`prod`**
+
+CI парсит суффикс и обновляет `sova-deploy/apps/{app}/values-{env}.yaml` → ArgoCD sync.
+
+Подробнее: [Система тегов CI/CD](./tags.md).
+
+---
+
+## Жизненный цикл задачи (пошагово)
+
+### 1. Разработка
+
+```bash
+git checkout prod
+git pull origin prod
+git checkout -b feature/SOVA-123-add-widget
+# ... commits ...
+git push origin feature/SOVA-123-add-widget
+```
+
+### 2. Code review → test
+
+1. В Gitea: **Pull Request** `feature/SOVA-123-add-widget` → **`test`**
+2. Review, approve, merge
+3. **Создать тег на ветке `test`** → автодеплой на test-контур (см. ниже)
+
+### 3. QA на test
+
+Тестировщик проверяет на test-URL (например http://api.test.sova.local).
+
+### 4. Промоушен на stage
+
+1. **Pull Request** `feature/SOVA-123-add-widget` → **`stage`** (не `test` → `stage`!)
+2. Merge после approve
+3. **Тег на ветке `stage`**, например `backend-v1.0.2-stage`
+4. Регресс / нагрузочное тестирование на stage-контуре *(контур — в планах)*
+
+### 5. Релиз в prod
+
+1. Когда все задачи в `stage` проверены: **Pull Request** `stage` → **`prod`**
+2. Merge (минимум 1 approval на `prod`)
+3. **Тег на ветке `prod`**, например `backend-v1.0.2-prod`
+4. Деплой на production *(контур — в планах)*
+
+---
+
+## Как создать тег в Gitea (UI)
+
+Пример: выкатить backend `v1.0.2` на **test** после merge PR в `test`.
+
+### Способ A — Releases (рекомендуется)
+
+1. Откройте http://git.sova.local/sova/backend
+2. **Releases** → **New Release**
+3. **Tag name:** `backend-v1.0.2-test`
+4. **Target branch:** выберите **`test`** (не prod!)
+5. **Release title:** `Test release 1.0.2` (произвольно)
+6. **Publish Release**
+
+Gitea создаст тег и отправит push → запустится workflow **backend-ci-cd**.
+
+### Способ B — Create tag на ветке
+
+1. **Code** → выпадающий список веток → **`test`**
+2. Коммит, который нужно выкатить → **⋯** → **Create tag**
+3. **Tag name:** `backend-v1.0.2-test`
+4. **Create**
+
+### Способ C — CLI (локально)
+
+```bash
+cd k3s-test
+./scripts/release-tag.sh backend backend-v1.0.2-test
+# checkout test, tag, push — автоматически
+```
+
+### Проверка после тега
+
+1. http://git.sova.local/sova/backend/actions — jobs **success**
+2. http://argocd.sova.local — `backend-test` **Synced**
+3. `kubectl get deploy backend -n sova-test` — образ `git.sova.local/sova/backend:backend-v1.0.2-test`
+
+---
+
+## Пример полного flow (backend, задача SOVA-123)
+
+| Шаг | Действие | Gitea / CLI |
+|-----|----------|-------------|
+| 1 | Ветка от prod | `git checkout -b feature/SOVA-123 prod` |
+| 2 | PR → test | UI: New Pull Request → base: **test** |
+| 3 | Merge PR | Merge Pull Request |
+| 4 | Тег test | Release: `backend-v1.0.2-test` на ветке **test** |
+| 5 | QA OK | — |
+| 6 | PR → stage | UI: feature/SOVA-123 → base: **stage** |
+| 7 | Тег stage | `backend-v1.0.2-stage` на ветке **stage** |
+| 8 | Регресс OK | — |
+| 9 | PR stage → prod | UI: base: **prod** |
+| 10 | Тег prod | `backend-v1.0.2-prod` на ветке **prod** |
+
+---
+
+## Hotfix (срочный фикс в prod)
+
+1. Ветка от **`prod`:** `hotfix/SOVA-999-critical`
+2. Fix → PR → **`test`** → тег `*-test` → быстрая проверка
+3. PR **`hotfix/SOVA-999`** → **`stage`** → тег `*-stage` *(или skip stage для critical — по решению лида)*
+4. PR **`hotfix/SOVA-999`** → **`prod`** → тег `*-prod`
+5. **Back-merge:** PR `prod` → `stage` и `prod` → `test`, чтобы ветки не разъехались
+
+Hotfix **не** мержится через `test` → `stage` целиком — только своя ветка.
+
+---
+
+## Защита веток (Branch Protection)
+
+Настроено скриптом `./scripts/setup-gitea-branch-protection.sh`:
+
+| Ветка | Direct push | Merge | Approvals |
+|-------|-------------|-------|-----------|
+| `prod` | запрещён | через PR | 1 |
+| `stage` | запрещён | через PR | 0 |
+| `test` | запрещён | через PR | 0 |
+
+Изменения попадают в `prod` / `stage` / `test` **только через Pull Request**.
+
+---
+
+## CI/CD по контурам
+
+### Test — **работает сейчас**
+
+| Триггер | Тег `*-test` на ветке `test` |
+| Pipeline | test → build-and-push → deploy-gitops |
+| GitOps | `apps/{app}/values-test.yaml` в `sova-deploy` |
+| ArgoCD | `backend-test`, `cabinet-test`, … |
+| URLs | `*.test.sova.local`, `docs.sova.local` |
+
+Bootstrap веток (один раз):
+
+```bash
+./scripts/setup-git-flow-branches.sh
+./scripts/setup-gitea-branch-protection.sh
+```
+
+### Stage — **описано, внедрение позже**
+
+| План | |
+|------|---|
+| Триггер | Тег `*-stage` на ветке `stage` |
+| GitOps | `values-stage.yaml` (заготовки уже в `sova-deploy`) |
+| ArgoCD | `backend-stage`, `cabinet-stage`, … *(Applications не созданы)* |
+| Namespace | `sova-stage` |
+| Ingress | `*.stage.sova.local` |
+| Кластер | отдельная VM / namespace group |
+
+CI **уже поддерживает** суффикс `-stage` — достаточно поднять stage-кластер и ArgoCD apps.
+
+### Prod — **описано, внедрение позже**
+
+| План | |
+|------|---|
+| Триггер | Тег `*-prod` на ветке `prod` |
+| GitOps | `values-prod.yaml` *(создать при внедрении)* |
+| ArgoCD | `backend-prod`, … + RBAC |
+| Secrets | SealedSecrets / external secrets |
+| Ingress | боевые домены |
+
+---
+
+## sova-mocks
+
+Репозиторий `sova-mocks` участвует в git-flow (**ветки prod/test/stage**), но **без tag CI**.
+
+Обновление моков на test-контуре:
+
+1. PR изменений → `test`
+2. ArgoCD app `mocks-test` следит за `sova-mocks` **`main`** сегодня — при миграции на ветки: `targetRevision: test`
+3. Sync в ArgoCD UI или автосync
+
+---
+
+## Первичная настройка (админ)
+
+```bash
+cd k3s-test
+
+# 1. Ветки prod / test / stage во всех app-репах
+./scripts/setup-git-flow-branches.sh
+
+# 2. Branch protection
+./scripts/setup-gitea-branch-protection.sh
+
+# 3. CI secrets (если ещё не делали)
+./scripts/bootstrap-gitea-ci-secrets.sh
+./scripts/configure-k3s-registry.sh
+
+# 4. Пример релиза на test
+./scripts/release-tag.sh backend backend-v1.0.1-test
+```
+
+После `setup-git-flow-branches.sh` default branch в Gitea = **`prod`**, legacy **`main`** удаляется с remote.
+
+---
+
+## Связанные документы
+
+- [Система тегов CI/CD](./tags.md)
+- [Gitea: теги и CI/CD (скриншоты)](./guides/gitea-ci.md)
+- [ArgoCD: приложения test-контура](./guides/argocd.md)
@@ -2,7 +2,7 @@

 В test-контуре каждый сервис (`backend`, `adminpanel`, `cabinet`, `docs`) — **отдельный репозиторий** в Gitea. Релиз = **git-тег** → Gitea Actions → Docker-образ → обновление `sova-deploy` → ArgoCD sync.

-Подробнее о формате тегов: [Система тегов CI/CD](../tags).
+Подробнее: [Git-flow](../git-flow) (ветки prod/test/stage, PR), [Система тегов CI/CD](../tags).

 ## 1. Вход в Gitea

@@ -42,14 +42,18 @@ Workflow в каждом app-репозитории:

 ## 4. Как выкатить тег (с Mac)

+Тег ставится **на ветку контура** (`test`, `stage`, `prod`). Пример для test:
+
 ```bash
 cd k3s-test
-./scripts/release-test-tag.sh backend   backend-v1.0.1-test
-./scripts/release-test-tag.sh adminpanel adminpanel-v1.0.1-test
-./scripts/release-test-tag.sh cabinet   cabinet-v1.0.1-test
-./scripts/release-test-tag.sh docs      docs-v1.0.1-test
+./scripts/release-tag.sh backend   backend-v1.0.1-test
+./scripts/release-tag.sh adminpanel adminpanel-v1.0.1-test
+./scripts/release-tag.sh cabinet   cabinet-v1.0.2-test
+./scripts/release-tag.sh docs      docs-v1.0.5-test
 ```

+Создание тега через UI Gitea (Releases → Target branch **test**) — пошагово в [Git-flow](../git-flow#как-создать-тег-в-gitea-ui).
+
 Скрипт создаёт аннотированный тег и пушит в Gitea. Тег виден в репозитории:

 ![Теги backend](../screenshots/05-gitea-backend-tags.png)
@@ -15,7 +15,8 @@

 ### Текстовая документация

- [Test-контур: что сделано и перенос на сервер](./test-contour-article) — полная статья
+- [Git-flow: ветки, теги, автодеплой](./git-flow) — prod / test / stage, PR, пример через UI Gitea
+- [Test-контур: что сделано и перенос на server](./test-contour-article) — полная статья
 - [Система тегов CI/CD](./tags) — формат тегов и release-скрипт
 - [ArgoCD: sova-root и data-test](./argocd-apps) — зачем эти приложения и почему «нельзя войти»

@@ -2,6 +2,8 @@

 Каждое приложение в Gitea публикуется **отдельным репозиторием** и выпускается **своим тегом**. Тег запускает Gitea Actions: сборка Docker-образа → push в registry → обновление `values-{env}.yaml` в `sova-deploy`.

+> Полный git-flow (ветки prod/test/stage, PR, hotfix): [Git-flow](./git-flow.md)
+
 ## Формат тега

 ```
@@ -11,36 +13,42 @@
 | Часть | Пример | Описание |
 |-------|--------|----------|
 | `component` | `backend`, `adminpanel`, `cabinet`, `docs` | имя сервиса |
-| `semver` | `1.0.1` | версия образа |
-| `env` | `test`, `stage` | контур (подставляется в `values-{env}.yaml`) |
+| `semver` | `1.0.1`, `1.0.2` | версия образа |
+| `env` | `test`, `stage`, `prod` | контур → `values-{env}.yaml` |

-Примеры для test-контура:
+**Тег создаётся на ветке с тем же именем, что и env:** `backend-v1.0.2-test` ставится на ветку **`test`**.

-| Репозиторий Gitea | Тег | Helm values |
-|-------------------|-----|-------------|
-| `sova/backend` | `backend-v1.0.1-test` | `apps/backend/values-test.yaml` |
-| `sova/adminpanel` | `adminpanel-v1.0.1-test` | `apps/adminpanel/values-test.yaml` |
-| `sova/cabinet` | `cabinet-v1.0.1-test` | `apps/cabinet/values-test.yaml` |
-| `sova/docs` | `docs-v1.0.1-test` | `apps/docs/values-test.yaml` |
+Примеры:

-`sova-deploy` и `sova-mocks` **не** собираются по тегам — их меняют вручную или через bootstrap; ArgoCD подхватывает `main`.
+| Репозиторий Gitea | Тег | Ветка | Helm values |
+|-------------------|-----|-------|-------------|
+| `sova/backend` | `backend-v1.0.1-test` | `test` | `apps/backend/values-test.yaml` |
+| `sova/adminpanel` | `adminpanel-v1.0.1-test` | `test` | `apps/adminpanel/values-test.yaml` |
+| `sova/cabinet` | `cabinet-v1.0.2-test` | `test` | `apps/cabinet/values-test.yaml` |
+| `sova/docs` | `docs-v1.0.5-test` | `test` | `apps/docs/values-test.yaml` |
+| `sova/backend` | `backend-v1.0.2-stage` | `stage` | `apps/backend/values-stage.yaml` *(stage-контур — план)* |
+| `sova/backend` | `backend-v1.0.2-prod` | `prod` | `values-prod.yaml` *(prod — план)* |
+
+`sova-deploy` и `sova-mocks` **не** собираются по тегам приложений — deploy через GitOps / ArgoCD.

 ## Release-скрипт

 ```bash
-./scripts/release-test-tag.sh backend   backend-v1.0.1-test
-./scripts/release-test-tag.sh adminpanel adminpanel-v1.0.1-test
-./scripts/release-test-tag.sh cabinet   cabinet-v1.0.1-test
-./scripts/release-test-tag.sh docs      docs-v1.0.1-test
+./scripts/release-tag.sh backend   backend-v1.0.1-test
+./scripts/release-tag.sh adminpanel adminpanel-v1.0.1-test
+./scripts/release-tag.sh cabinet   cabinet-v1.0.2-test
+./scripts/release-tag.sh docs      docs-v1.0.5-test
 ```

-Скрипт создаёт аннотированный тег в локальном зеркале репозитория и пушит в Gitea. Workflow парсит суффикс `-test` и обновляет соответствующий `values-test.yaml`.
+Скрипт checkout ветки `test` (или env из суффикса тега), создаёт аннотированный тег и пушит в Gitea.
+
+`release-test-tag.sh` — алиас для совместимости.

 ## Pipeline (общая схема)

 ```mermaid
 flowchart LR
-  tag["git tag push"] --> test["job: test"]
+  tag["git tag on env branch"] --> test["job: test"]
  test --> build["build-and-push"]
  build --> registry["Gitea registry"]
  build --> deploy["deploy-gitops"]
@@ -73,7 +81,7 @@ flowchart LR
 ./scripts/import-images-to-vm.sh local-test
 ```

-Образы с тегом `local-test` и `pullPolicy: Never`/`IfNotPresent` — для первого деплоя до настройки registry.
+Образы с тегом `local-test` — для первого деплоя до настройки registry.

 ## Проверка

@@ -81,10 +89,9 @@ flowchart LR
 # Workflow
 open http://git.sova.local/sova/backend/actions

-# Образ в registry
-curl -u gitea_admin:PASSWORD http://git.sova.local/v2/sova/backend/tags/list
-
 # ArgoCD
 kubectl get applications -n argocd
 kubectl get deploy -n sova-test
 ```
+
+Создание тега через UI Gitea — см. [Git-flow → Как создать тег](./git-flow.md#как-создать-тег-в-gitea-ui).