Окружения

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

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

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	Поддерживаются
Создаётся	Автоматически при создании проекта

Development

Системное окружение для development scope. Оно создаётся автоматически и используется для development-переменных и runtime-конфигурации, но не является отдельной веткой автодеплоя.

Характеристика	Значение
Ветки	Не привязано к ветке
URL	Не создаёт отдельный public URL
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 и scope

Переменную можно применить ко всем или только к выбранным окружениям:

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

Осторожно

Текущая модель хранит одну definition на Project/key. Она не поддерживает разные values одного key для разных Environment. Для изменения существующего scope или plain/secret category CLI требует явные safety flags. Полноценные Environment-owned overrides появятся в environment-first config model.

Пример без конфликтующих overrides:

# All environments
PUBLIC_API_URL=https://api.example.com

# Preview only
PREVIEW_BANNER=true

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

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

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

Заметка

Development окружение не поддерживает custom domains. Для публичных URL используйте Production, Preview или Custom.

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

Auto Deploy

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

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

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

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

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

Заметка

Production, Preview и Development окружения нельзя удалить. У системных окружений редактируется только доступная часть настроек: например, retention, Auto Deploy для Preview и blue-green для Production/Preview. Custom Domains можно добавлять к Production, Preview и 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 --environment preview

# Установить plain value
nrz env set PUBLIC_API_URL --value https://api.example.com --plain --all

# Установить secret без shell history
printf %s "$API_TOKEN" | nrz env set API_TOKEN --stdin --secret --environment preview

# Запустить локальную команду с materialized context без dotenv
nrz env exec --environment preview -- npm run dev

# Удалить project-wide definition
nrz env delete API_TOKEN --all

См. 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

Задайте общие values с scope All Environments, а Environment-specific keys с scope Selected. До environment-first migration не создавайте разные values одного key для разных окружений:

# All Environments
API_URL=https://api.example.com

# Staging only
STAGING_FEATURE_GATE=true

# Preview only
PREVIEW_BANNER=true

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

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

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

// Переменная автоматически соответствует текущему окружению
const dbUrl = process.env.DATABASE_URL;
// Value comes from the immutable Deployment Environment snapshot.

Совет

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

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 — настройка доменов
• Деплои — типы деплоев