CI/CD пайплайны

Проект использует GitHub Actions для автоматизации тестирования, сборки и деплоя. Все workflows находятся в .github/workflows/.

Обзор пайплайна

mermaid

flowchart LR
    subgraph PR["Pull Request"]
        CI[ci.yml<br/>Lint/Test/Build]
    end
    subgraph Dev["Push to dev"]
        DeployDev[deploy-to-dev.yml]
    end
    subgraph Main["Push to main"]
        DeployProd[deploy-to-prod.yml]
        Docs[docs.yml]
        Release[release.yml]
    end

    PR -->|must pass| Merge["Merge to dev"]
    Merge --> Dev
    Dev -->|автоматический<br/>деплой| DeployDev
    DeployDev -->|turbo cache| CFDev["Cloudflare<br/>Workers Dev"]

    Merge -->|merge| Main
    Main --> DeployProd
    Main --> Docs
    Main --> Release
    DeployProd -->|turbo cache| CFProd["Cloudflare<br/>Workers Prod"]
    Docs -->|production| Pages["CF Pages<br/>integ.docs.happ.tools"]
    Release -->|auto-tag| Tags["Git Tags"]

GitHub Actions Workflows

Naming Convention для Workers

Проект использует отдельные воркеры для каждого окружения:

Интеграция	Dev Worker	Production Worker
Sofa	`integ-sofa-dev`	`integ-sofa`
Gateway	`integ-gateway-dev`	`integ-gateway`

Конфигурация через generate:env:

wrangler.toml генерируется динамически командой pnpm generate:env -- <env> с уже подставленным именем:

bash

# Dev: wrangler.toml содержит name = "integ-sofa-dev"
pnpm generate:env -- dev

# Prod: wrangler.toml содержит name = "integ-sofa"
pnpm generate:env -- prod

При деплое:

bash

wrangler deploy  # → Имя берётся из сгенерированного wrangler.toml

1. CI Pipeline (`ci.yml`)

Запускается на Pull Requests в ветки dev и main, а также при ручном запуске.

Что делает:

Устанавливает зависимости (pnpm)
Запускает linting (ESLint), unit тесты (Vitest) и build через один Turbo run
Работает только с affected пакетами (измененными в PR)

Оптимизации:

paths-ignore - CI не запускается для изменений в docs/, *.md, .vscode/, .idea/
--filter='[origin/base...HEAD]' - lint/test/build только для измененных пакетов
SKIP_ENV=true - пропускает генерацию .env файлов
Turbo Remote Cache через Vercel - переиспользование кэша между PR
Caching pnpm зависимостей через GitHub Actions

yaml

# Один turbo run для всего — он сам распараллелит
- name: Lint, Test, Build (affected only)
  run: pnpm turbo lint test build --filter='[origin/${{ github.base_ref }}...HEAD]' --concurrency=4
  env:
    SKIP_ENV: "true"

Статус: ✅ Обязателен перед мержем PR

2. Deploy to Dev (`deploy-to-dev.yml`)

Запускается при push в dev ветку, деплоит в dev окружение Cloudflare Workers.

Последовательность шагов:

2.1. Setup и сборка

bash

pnpm install
pnpm build                              # Собрать все пакеты

2.2. Деплой всех интеграций и Gateway

bash

turbo deploy:dev --filter='./integrations/*' --filter='integ-gateway'

Turbo автоматически определяет, какие пакеты изменились, и деплоит только их благодаря кэшированию.

2.3. Health Check

bash

# 10 попыток проверить https://integ.dev.happ.tools/health
curl -sf https://integ.dev.happ.tools/health

Оптимизации:

🚀 Turbo cache - деплоит только измененные пакеты
💾 actions/cache - кэширует .turbo между CI запусками
🏥 Health check - убеждается что сервис запустился

Секреты:

CLOUDFLARE_WORKERS_API_TOKEN - API token Cloudflare
CLOUDFLARE_ACCOUNT_ID - ID аккаунта Cloudflare
DEV_DOPPLER_TOKEN - Doppler token для dev окружения

3. Deploy to Prod (`deploy-to-prod.yml`)

Запускается при push в main ветку, деплоит в production Cloudflare Workers.

Отличия от Dev:

Требует environment: production для дополнительной безопасности
Использует origin/main вместо origin/dev для определения изменений
URL для health check: https://integ.happ.tools/health
Concurrency: cancel-in-progress: false (не отменяет предыдущие деплои)
Тесты запускаются только если workflow вызван вручную (workflow_dispatch)

Ключевые секреты:

PROD_DOPPLER_TOKEN - Doppler token для production

bash

# Только если manual trigger
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
  pnpm test
fi

4. Deploy Docs (`docs.yml`)

Автоматический деплой документации на Cloudflare Pages (один проект integ-docs).

Когда запускается:

Push в main ветку (только если изменились файлы в docs/)
Ручной запуск

Что делает:

bash

pnpm docs:build                         # VitePress build
wrangler pages deploy docs/.vitepress/dist --project-name=integ-docs --branch=$BRANCH

URL:

Ветка	URL
`main`	https://integ.docs.happ.tools

Примечание: Custom domain integ.docs.happ.tools настроен в Cloudflare Pages → Custom domains и указывает на integ-docs.pages.dev.

Секреты:

CLOUDFLARE_PAGES_API_TOKEN - API token для Pages
CLOUDFLARE_ACCOUNT_ID - Account ID

5. Release (`release.yml`)

Автоматическое тагирование релизов на основе merge коммитов.

Как это работает:

Извлечение версии из merge commit сообщения

Format: "Merge pull request #123 from org/release/1.2.3"
Или:    "Merge branch 'release/1.2.3'"

Проверка существования тега - если tag уже есть, пропускается

Создание и push тага

bash

git tag -a "v1.2.3" -m "Release v1.2.3"
git push origin "v1.2.3"

Пример использования:

Создать pull request из ветки release/1.2.3 в main. После мержа:

Автоматически создастся tag v1.2.3
Будет доступен в GitHub Releases

Оптимизации и лучшие практики

1. Turbo Remote Cache

Проект использует Turbo Remote Cache через Vercel для максимального ускорения CI/CD. Кэш распределяется между:

Разными PR
CI и локальной разработкой
Разными разработчиками

Конфигурация в workflows:

yaml

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Локальная настройка:

bash

npx turbo login
npx turbo link

Когда кэш инвалидируется:

Изменения в исходных файлах (src/**)
Изменения в wrangler.toml или package.json
Изменения конфига (tsconfig.json, eslint.config.js)

2. Инкрементальный деплой

Turbo автоматически определяет, какие пакеты изменились:

bash

# Деплоит все интеграции и gateway, но Turbo пропустит unchanged
turbo deploy:dev --filter='./integrations/*' --filter='integ-gateway'

Это экономит время и снижает риск регрессий в неизменных интеграциях.

3. Concurrency Groups

Предотвращает одновременное выполнение деплоев:

yaml

concurrency:
  group: deploy-dev-${{ github.ref }}
  cancel-in-progress: true # Отмена старого при новом push

Dev: cancel-in-progress: true - отменяет старый деплой если был новый push Prod: cancel-in-progress: false - ждет завершения старого деплоя

4. SKIP_ENV Флаг

В CI используется SKIP_ENV=true для пропуска генерации .env:

bash

pnpm turbo lint --concurrency=4
env:
  SKIP_ENV: "true"

Почему это нужно:

В CI нет доступа к Doppler (генерация .env бесполезна)
Экономит ~5-10 секунд в каждом CI запуске
Пакеты обрабатывают этот флаг и пропускают валидацию env

5. Health Checks

После деплоя Gateway проверяется его здоровье:

bash

for i in {1..10}; do
  if curl -sf https://integ.dev.happ.tools/health > /dev/null 2>&1; then
    echo "✅ Health check passed!"
    exit 0
  fi
  sleep 5
done
exit 1

Логика:

10 попыток с интервалом 5 секунд
Если успешно - продолжить
Если все попытки неудачны - fail workflow

GitHub Secrets (требуется для CI/CD)

Все следующие секреты должны быть установлены в репозитории Settings → Secrets:

Секрет	Описание	Где получить
`CLOUDFLARE_WORKERS_API_TOKEN`	API token для Cloudflare Workers	Cloudflare Dashboard
`CLOUDFLARE_ACCOUNT_ID`	ID аккаунта Cloudflare	Cloudflare Dashboard → Account
`CLOUDFLARE_PAGES_API_TOKEN`	API token для Cloudflare Pages	Cloudflare Dashboard
`DEV_DOPPLER_TOKEN`	Doppler token для dev конфига	Doppler → Project → Settings
`PROD_DOPPLER_TOKEN`	Doppler token для prod конфига	Doppler → Project → Settings
`TURBO_TOKEN`	Turbo Remote Cache token	Vercel Dashboard

GitHub Variables (Settings → Variables):

Variable	Описание	Где получить
`TURBO_TEAM`	Vercel team slug	Vercel Dashboard → Team Settings

Примечание: Tokens должны иметь минимальные необходимые permissions для безопасности.

Мониторинг и отладка

Просмотр логов workflow

Перейти в GitHub → Actions
Выбрать нужный workflow run
Кликнуть на job и посмотреть step логи

Локальный запуск workflow

Использовать act для локального тестирования:

bash

# Установка
brew install act

# Запуск конкретного workflow
act -j build -l        # List jobs
act -j build           # Run specific job

Типичные ошибки

Ошибка	Решение
`SKIP_ENV=true` не работает	Проверить что env переменная передана в step
Health check fails	Проверить logs Gateway: `pnpm --filter integ-gateway dev`
Secrets не найдены	Проверить настройки GitHub → Settings → Secrets
Turbo cache не работает	Удалить `.turbo` папку локально и в CI

Производительность CI/CD

Текущие метрики

С Turbo Remote Cache и affected filter:

CI pipeline: ~1-2 минуты (с кэшем может быть < 1 мин)
Dev deploy: ~2-3 минуты (зависит от количества измененных интеграций)
Prod deploy: ~2-3 минуты (+ health check)
Docs deploy: ~1-2 минуты

Применённые оптимизации

Turbo Remote Cache - кэш переиспользуется между PR и локальной разработкой
Affected filter - CI обрабатывает только измененные пакеты:
bash
```
turbo lint test build --filter='[origin/dev...HEAD]'
```
1
Path filters - CI не запускается для docs, md, IDE файлов
Один turbo run - lint, test, build в одной команде, turbo сам распараллелит
Параллелизм: Ограничен до 4 для стабильности
bash
```
turbo lint test build --concurrency=4
```
1

Смежные документы

SCRIPTS.md — детальное описание утилитных скриптов
DEVELOPMENT.md — локальная разработка
PRODUCTION.md — deployment в production
SECRETS.md — управление секретами

CI/CD пайплайны ​

Обзор пайплайна ​

GitHub Actions Workflows ​

Naming Convention для Workers ​

1. CI Pipeline (ci.yml) ​

2. Deploy to Dev (deploy-to-dev.yml) ​

2.1. Setup и сборка ​

2.2. Деплой всех интеграций и Gateway ​

2.3. Health Check ​

3. Deploy to Prod (deploy-to-prod.yml) ​

4. Deploy Docs (docs.yml) ​

5. Release (release.yml) ​

Оптимизации и лучшие практики ​

1. Turbo Remote Cache ​

2. Инкрементальный деплой ​

3. Concurrency Groups ​

4. SKIP_ENV Флаг ​

5. Health Checks ​

GitHub Secrets (требуется для CI/CD) ​

Мониторинг и отладка ​

Просмотр логов workflow ​

Локальный запуск workflow ​

Типичные ошибки ​

Производительность CI/CD ​

Текущие метрики ​

Применённые оптимизации ​

Смежные документы ​

CI/CD пайплайны

Обзор пайплайна

GitHub Actions Workflows

Naming Convention для Workers

1. CI Pipeline (`ci.yml`)

2. Deploy to Dev (`deploy-to-dev.yml`)

2.1. Setup и сборка

2.2. Деплой всех интеграций и Gateway

2.3. Health Check

3. Deploy to Prod (`deploy-to-prod.yml`)

4. Deploy Docs (`docs.yml`)

5. Release (`release.yml`)

Оптимизации и лучшие практики

1. Turbo Remote Cache

2. Инкрементальный деплой

3. Concurrency Groups

4. SKIP_ENV Флаг

5. Health Checks

GitHub Secrets (требуется для CI/CD)

Мониторинг и отладка

Просмотр логов workflow

Локальный запуск workflow

Типичные ошибки

Производительность CI/CD

Текущие метрики

Применённые оптимизации

Смежные документы