Окружения

Окружение (Environment) — это конфигурация для определённого типа деплоев. Окружения позволяют иметь разные настройки для production и preview версий приложения.

Типы окружений

Production

Основное окружение для production версии приложения.

Характеристика	Значение
Ветка	Основная ветка (main, master)
URL	Production alias: project-workspace.onreza.app
Custom Domains	Поддерживаются
Создаётся	Автоматически при создании проекта

Заметка

Production окружение всегда отслеживает основную ветку репозитория. Изменить это нельзя.

Preview

Окружение для preview деплоев — тестирования изменений до мержа. При деплое в preview окружение статус деплоя проходит через UPLOADING во время загрузки артефактов.

Характеристика	Значение
Ветки	Все ветки кроме main
URL	Branch alias: project-git-branch-workspace.onreza.app
Custom Domains	Не поддерживаются
Создаётся	Автоматически при создании проекта

Custom

Пользовательские окружения для специфических сценариев.

Характеристика	Значение
Ветки	Настраиваемый паттерн
URL	Зависит от настройки
Custom Domains	Поддерживаются
Создаётся	Вручную

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

• Staging — предрелизное тестирование
• QA — окружение для QA команды
• Demo — демо для клиентов

Создание Custom окружения

1. Откройте настройки проекта

   Перейдите в проект → Settings → Environments

2. Нажмите “Add Environment”

3. Заполните форму

   Поле	Описание
   Name	Название (например, “Staging”)
   Type	Custom
   Branch Pattern	Паттерн ветки
   Match Type	Тип сопоставления

4. Сохраните

Branch Pattern (Паттерн ветки)

Определяет какие ветки относятся к окружению.

Match Types

Тип	Описание	Пример паттерна	Совпадает с
Equals	Точное совпадение	staging	только staging
Starts With	Начинается с	release/	release/1.0, release/2.0
Ends With	Заканчивается на	-prod	feature-prod, hotfix-prod

Примеры

# Staging окружение
Pattern: staging
Match: Equals
→ Ветка 'staging' → Staging окружение

# Release окружения
Pattern: release/
Match: Starts With
→ Ветка 'release/1.0' → Custom окружение

# Hotfix в production
Pattern: hotfix-
Match: Starts With
→ Ветка 'hotfix-urgent' → Custom окружение

Environment Variables по окружениям

Каждое окружение может иметь свои переменные:

1. Откройте Settings → Environment Variables
2. При создании переменной выберите Scope → Selected
3. Отметьте нужные окружения
4. Сохраните

Пример:

# Production
DATABASE_URL=postgres://prod-db/app
API_URL=https://api.example.com

# Preview
DATABASE_URL=postgres://staging-db/app
API_URL=https://api.staging.example.com

# Custom (Staging)
DATABASE_URL=postgres://staging-db/app
API_URL=https://api.staging.example.com

Custom Domains по окружениям

Production и Custom окружения могут иметь свои домены:

Окружение	Домен
Production	app.example.com
Staging (Custom)	staging.app.example.com

Заметка

Preview окружения не поддерживают custom domains — используйте технические URL.

→ Подробнее о доменах

Auto Deploy

Для каждого окружения можно настроить автодеплой:

• Включён — webhook триггерит деплой при пуше в соответствующую ветку
• Выключен — деплои только вручную

1. Откройте Settings → Environments
2. Выберите окружение
3. Включите/выключите Auto Deploy
4. Сохраните

Редактирование окружения

1. Откройте Settings → Environments
2. Нажмите на окружение
3. Измените настройки
4. Сохраните

Заметка

Production окружение нельзя удалить или редактировать — все его настройки зафиксированы. Preview окружение нельзя удалить, но можно настроить Auto Deploy. Custom Domains можно добавлять к Production и Custom окружениям.

Удаление Custom окружения

1. Откройте Settings → Environments
2. Найдите Custom окружение
3. Нажмите удалить
4. Подтвердите

Осторожно

При удалении окружения связанные деплои теряют привязку к нему, но продолжают работать и остаются доступны по своим уникальным URL.

Приоритет окружений

Когда ветка подходит под несколько окружений, используется приоритет:

1. Custom (с более специфичным паттерном)
2. Production (для main ветки)
3. Preview (для всех остальных)

Пример:

Ветка: staging
Окружения:
  - Production (main) — не совпадает
  - Preview (all except main) — совпадает
  - Custom "Staging" (staging, Equals) — совпадает, более специфичный

→ Используется Custom "Staging"

Use Cases

Staging окружение

Name: Staging
Type: Custom
Pattern: staging
Match: Equals

• Отдельные environment variables
• Отдельный custom domain: staging.example.com
• Для финального тестирования перед production

Release branches

Name: Release
Type: Custom
Pattern: release/
Match: Starts With

• release/1.0, release/2.0 и т.д.
• Для подготовки релизов

Feature preview для определённой команды

Name: Design Preview
Type: Custom
Pattern: design-
Match: Starts With

• design-header, design-footer и т.д.
• Отдельный domain для дизайнеров: design.preview.example.com

API доступ

Управление окружениями и их переменными доступно через CLI:

# Список переменных окружения
nrz env list

# Установить переменную окружения
nrz env set <key> <value>

# Удалить переменную окружения
nrz env delete <key>

# Скачать переменные в .env.local
nrz env pull

См. CLI Reference для подробностей.

Workflow: Development → Staging → Production

Типичный flow для команды с тремя окружениями:

1. Настройка окружений

Окружение	Branch Pattern	Match	Custom Domain
Production	main	(авто)	app.example.com
Staging	staging	Equals	staging.example.com
Preview	все остальные	(авто)	—

2. Environment Variables по окружениям

Задайте переменные с scope Selected для каждого окружения:

# Production (scope: Production)
DATABASE_URL=postgres://prod-host/mydb
API_URL=https://api.example.com
LOG_LEVEL=warn

# Staging (scope: Staging)
DATABASE_URL=postgres://staging-host/mydb
API_URL=https://api.staging.example.com
LOG_LEVEL=debug

# Preview (scope: Preview)
DATABASE_URL=postgres://dev-host/mydb
API_URL=https://api.dev.example.com
LOG_LEVEL=debug

Общие переменные (одинаковые для всех) задайте с scope All Environments.

3. Flow разработки

feature branch → Preview деплой → Code review
                                       ↓
                              Merge в staging
                                       ↓
                         Staging деплой → QA тестирование
                                       ↓
                              Merge в main
                                       ↓
                         Production деплой (автоматический)

4. Доступ к переменным в коде

import { env } from '@onreza/runtime/env';

// Переменная автоматически соответствует текущему окружению
const dbUrl = env.get('DATABASE_URL');
// Production → postgres://prod-host/mydb
// Staging    → postgres://staging-host/mydb
// Preview    → postgres://dev-host/mydb

Совет

Для быстрого управления переменными используйте CLI: nrz env set KEY VALUE

Retry policy

При ошибках сборки автоматически применяется политика повторных попыток. Настройки retry policy зависят от типа окружения и влияют на поведение билдов во всех деплоях.

Troubleshooting

Деплой попал не в то окружение

1. Проверьте Branch Pattern — возможно он слишком широкий
2. Проверьте Match Type — Starts With vs Equals
3. Проверьте приоритет — Custom окружения имеют приоритет

Environment Variables не применились

1. Проверьте Scope переменных — они могут быть не для этого окружения
2. Убедитесь что деплой завершился после изменения
3. Проверьте что переменная не переопределена на уровне Project

См. также

• Environment Variables — переменные окружения
• KV Store — хранилище ключ-значение
• Custom Domains — настройка доменов
• Деплои — типы деплоев