sova/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

issues/27: docs git-flow prod test stage

Browse Source
This commit is contained in:
Valery Petrov
2026-05-28 19:19:52 +03:00
parent 0acf59c408
commit 11348a4e35
6 changed files with 318 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitea/workflows/build.yml
+1 -1
View File
@@ -5,7 +5,7 @@ on:
tags:
- 'docs-v*'
pull_request:
branches: [main]
branches: [prod, test, stage]
env:
REGISTRY: gitea-http.gitea.svc.cluster.local:3000
.vitepress/config.mts
+1
View File
@@ -104,6 +104,7 @@ export default defineConfig({
{ text: 'ArgoCD: приложения', link: '/infrastructure/test-contour/guides/argocd' },
{ text: 'Grafana / Prometheus / Loki', link: '/infrastructure/test-contour/guides/monitoring' },
{ text: 'Что сделано + перенос на сервер', link: '/infrastructure/test-contour/test-contour-article' },
{ text: 'Git-flow: ветки и релизы', link: '/infrastructure/test-contour/git-flow' },
{ text: 'Система тегов CI/CD', link: '/infrastructure/test-contour/tags' },
{ text: 'ArgoCD: sova-root и data-test', link: '/infrastructure/test-contour/argocd-apps' }
]
infrastructure/test-contour/git-flow.md
+278
View File
@@ -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)
infrastructure/test-contour/guides/gitea-ci.md
+9 -5
View File
@@ -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)
infrastructure/test-contour/index.md
+2 -1
View File
@@ -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) — зачем эти приложения и почему «нельзя войти»
infrastructure/test-contour/tags.md
+27 -20
View File
@@ -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).