Окружения в SourceCraft

Окружение — набор секретов и настроек доступа для определенной среды работы приложения. Например, окружения staging и production позволяют использовать одинаковую конфигурацию рабочего процесса CI/CD для развертывания на разных стендах, подставляя разные наборы секретов.

В SourceCraft можно определить, кто получает доступ к секретам окружения и управляет ими. Секреты используются в заданиях CI/CD, а ссылки между окружениями позволяют подключать общие секреты организации, проекта или репозитория.

Уровни окружений

Окружение принадлежит организации, проекту или репозиторию. Окружения организации и проекта позволяют хранить общие секреты для нескольких репозиториев. В заданиях CI/CD используются секреты окружений репозитория, в том числе полученные через ссылки на другие окружения.

Имя окружения уникально в пределах его владельца. Например, организация и репозиторий могут иметь собственные окружения production. Это независимые окружения: совпадение имен не объединяет их секреты. Чтобы использовать общие секреты, нужно явно подключить другое окружение.

Секреты

Секреты хранят конфиденциальные значения: пароли, токены, ключи доступа. В окружение можно добавить внутренний секрет SourceCraft или подключить секрет из Yandex Lockbox через сервисное подключение. Значения секретов маскируются в логах CI/CD.

В файле .sourcecraft/ci.yaml внутренний секрет окружения задается выражением ${{ secrets.<название_секрета> }}, например ${{ secrets.API_TOKEN }}. Окружение указывается в параметре environment рабочего процесса.

Чтобы передать секрет в скрипт кубика, присвойте выражение переменной в блоке env. Окружение хранит секреты, а env определяет, под какими именами они доступны процессам задания или кубика.

Открытые настройки, например адрес API или уровень логирования, задавайте в блоке env конфигурации CI/CD. Подробнее на странице Работа с переменными окружения в SourceCraft.

Подключение других окружений

Ссылка на окружение подключает его секреты к текущему окружению. Значения не копируются: при обращении к секрету выполняется поиск по ключу. Так можно централизованно обновлять общие секреты.

Подключать можно окружения того же владельца и его родительских ресурсов:

Текущее окружение	Какие окружения можно подключить
Организации	Другие окружения этой организации
Проекта	Другие окружения этого проекта и окружения его организации
Репозитория	Другие окружения этого репозитория, его проекта и организации

Нельзя подключить окружение постороннего репозитория, другого проекта или другой организации. Циклические подключения также запрещены. Например, если staging подключает shared, окружение shared не может подключить staging, в том числе через промежуточное окружение.

Приоритет значений

Секрет ищется по ключу в следующем порядке:

1. В собственных секретах текущего окружения.
2. В подключенных окружениях по порядку ссылок, начиная с первого приоритета. Для каждой ссылки сначала проверяется подключенное окружение, затем его ссылки.
3. В секретах, созданных непосредственно в организации, проекте или репозитории, которому принадлежит текущее окружение.

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

Используется первое найденное значение. Если изменить порядок ссылок или удалить собственный секрет, результат поиска может измениться. Подробнее в примере с общими секретами.

Доступ через ссылку

Секреты из подключенных окружений изменяются в окружении-источнике при наличии соответствующих прав. Чтобы переопределить значение только для текущего окружения, создайте в нем собственный секрет с тем же ключом. Для изменения секретов нужна роль Ответственный за окружение или выше в соответствующем окружении.

Для управления ссылками нужна роль Ответственный за окружение или выше в текущем окружении. Для подключения другого окружения репозитория пользователю также требуется право чтения его секретов. Для подключения окружения непубличной организации или проекта требуется участие в соответствующей организации или проекте.

Управление доступом

Роли окружений можно назначать отдельным пользователям и командам.

Создатель окружения автоматически получает в нем роль Администратор окружения.

Для окружений предусмотрены роли Просмотр окружения, Разработчик окружения, Ответственный за окружение и Администратор окружения.

Роль Просмотр репозитория включает Просмотр окружения, Ответственный за репозиторий — Ответственный за окружение, а Администратор репозитория — Администратор окружения. Эти права наследуются и через соответствующие роли проекта.

Роль Разработчик репозитория сама по себе не дает доступ к значениям секретов именованного окружения. Например, назначьте команде разработки роль Разработчик окружения в staging, а в production — Просмотр окружения. Команда сможет использовать секреты тестовой среды и просматривать информацию о продуктовом окружении без доступа к его секретам.

Как назначить роли, описано в разделе Настроить доступ.

Изменение и удаление окружений

Удаление ссылки на окружение деактивирует только подключение: само окружение-источник и его значения остаются доступны.

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

Тестовое и продуктовое окружения

В репозитории веб-приложения создайте окружения staging и production. В каждом сохраните секрет API_TOKEN с токеном доступа к API соответствующей среды. В staging назначьте команде разработки роль Разработчик окружения, а в production предоставьте доступ к секретам только участникам, которым нужно проверять продуктовое приложение.

Для тестовой среды укажите в рабочем процессе environment: staging, а для продуктовой — environment: production. В обоих случаях используйте одно выражение ${{ secrets.API_TOKEN }}: конфигурация обращения к секрету и скрипт остаются одинаковыми, а токен выбирается из соответствующего окружения. Полный пример конфигурации и скрипта приведен в инструкции.

Общие секреты и переопределение значений

Организация хранит общие секреты в окружении shared, а секреты для сервисов наблюдаемости — в observability. Окружение репозитория production подключает observability с первым приоритетом и shared — со вторым. Кроме того, в самом репозитории создан секрет REPO_API_KEY.

Ключ секрета	production	observability	shared	Секреты репозитория	Источник значения
API_TOKEN	Токен продуктовой среды	Токен наблюдаемости	Общий токен	Не задан	production — собственный секрет
MONITORING_TOKEN	Не задан	Токен наблюдаемости	Общий токен	Не задан	observability — первая ссылка
COMPANY_API_KEY	Не задан	Не задан	Общий ключ API	Не задан	shared — вторая ссылка
REPO_API_KEY	Не задан	Не задан	Не задан	Ключ репозитория	Сам репозиторий — после поиска по ссылкам

Если удалить собственный секрет API_TOKEN из production, будет использован токен из observability. Если после этого поставить shared первым в списке ссылок, будет использован общий токен.

Для получения общего секрета в CI/CD укажите в рабочем процессе environment: production и используйте ${{ secrets.COMPANY_API_KEY }}. Источник значения определяется по ссылкам окружения production.

В заданиях этого рабочего процесса выражение ${{ secrets.REPO_API_KEY }} получит секрет самого репозитория, поскольку его нет ни в production, ни в подключенных окружениях. Если секрет ORG_API_KEY создан непосредственно в организации, но отсутствует в ее окружениях shared и observability и в репозитории, выражение ${{ secrets.ORG_API_KEY }} его не получит: поиск по ссылкам не обращается к секретам самой организации.

Полезные ссылки

• Работа с окружениями в SourceCraft
• Непрерывная интеграция и непрерывное развертывание в SourceCraft
• Управлять секретами в репозитории SourceCraft
• Работа с переменными окружения в SourceCraft
• Управление доступом в SourceCraft