공유 환경 변수 그룹

An environment variable group holds values that several Orbit projects need, such as a shared API key or a database credential, in one place. Link the group to the projects that need it and every…

환경 변수 그룹은 공유 API 키나 데이터베이스 자격 증명처럼 여러 Orbit 프로젝트에서 필요한 값들을 한 곳에 보관합니다. 그룹을 필요한 프로젝트들에 연결하면 모든 빌드에서 해당 변수들을 가져오게 되므로, 키를 회전할 때 여섯 개 프로젝트마다 편집하는 대신 한 번만 편집하면 됩니다.

Env Groups 위치

Orbit을 열고 최상위 탐색에서 Env groups를 선택합니다. 페이지는 Shared env var groups라는 제목이며, 여러 Orbit 프로젝트에 공유되는 계정 수준의 그룹임을 설명합니다.

그룹은 프로젝트 위에 있습니다. 프로젝트의 자체 변수는 여전히 Env vars 탭에 있습니다: Environment Variables in Orbit을 참조하세요.

그룹 사용 시기

테스트는 간단합니다: 동일한 값이 둘 이상의 프로젝트에 붙여넣어지고 있습니까?

적합한 후보:

모든 프론트 엔드에서 사용하는 공유 분석 또는 오류 추적 키.
여러 내부 도구에서 사용하는 읽기 전용 복제 연결 문자열.
전체 계정에서 통신하는 서비스의 타사 API 키.
공통 기능 플래그 클라이언트 토큰.

부적합한 후보:

한 프로젝트에만 해당하는 항목입니다. 해당 프로젝트에 속합니다.
프로덕션과 미리보기 간에 다른 항목입니다. 그룹은 환경별이 아니므로, 환경에 따라 변경되는 값은 프로젝트의 자체 환경 변수에 속합니다.

그룹 만들기

New group을 클릭합니다.
Group name을 지정하고 최대 64자까지 입력합니다. 포함된 내용으로 이름을 지정합니다(예: 자격 증명이 속한 서비스).
선택적 Description을 추가합니다.
Create group을 클릭합니다.

계정은 최대 20개의 그룹을 보유할 수 있습니다. 한계에 도달하면 버튼에 **(limit reached)**가 표시되고 다른 그룹을 만들 수 없습니다.

그룹을 만들고, 편집하고, 삭제하려면 계정에 대한 소유자 또는 관리자 역할이 필요합니다. 개발자와 뷰어는 그룹을 볼 수 있지만 변경할 수 없습니다. 이는 의도적입니다: 그룹 편집은 여러 프로젝트에 한 번에 영향을 미칩니다.

변수 추가

그룹을 열고 Variables 섹션을 사용합니다:

Add variable을 클릭합니다.
키와 값을 입력합니다.
민감한 항목에 대해 Mark as secret을 선택합니다.
Save group을 클릭합니다.

비밀로 표시된 변수는 암호화되어 저장되며, 이후 패널에 값이 반환되지 않습니다. 목록에 키와 값 대신 Marked as secret (hidden) 표시기가 표시됩니다. 비밀이 아닌 값은 계속 표시되므로 한눈에 확인할 수 있습니다.

변수를 비밀로 표시하면 패널에서 다시 읽을 수 없습니다. 이것이 목표이지만, 그룹은 암호 관리자가 아닙니다. 팀이 이미 자격 증명을 보관하는 위치에서 권장 사본을 유지하고, 그룹을 배포 메커니즘으로 취급하세요.

비밀의 값을 변경하려면 새 값을 입력하고 저장합니다. 변수를 제거하려면 해당 행에서 Remove를 클릭하고 저장합니다.

프로젝트 연결

Linked projects 섹션은 계정의 모든 프로젝트를 나열합니다. 프로젝트를 클릭하여 연결하거나 연결을 해제합니다. 연결된 프로젝트는 강조 표시됩니다. 그룹을 저장하여 적용합니다.

연결된 프로젝트가 없는 그룹은 아무것도 하지 않으며, 섹션은 프로젝트를 연결할 때까지 No projects yet이라고 표시합니다.

그룹 변수는 빌드 시 주입되므로, 프로젝트를 연결하는 것은 현재 라이브 배포가 아닌 다음 빌드에 영향을 미칩니다. 지금 변경이 필요하면 재배포하세요: Deploying Your Project를 참조하세요.

우선순위

규칙은 페이지에 명시되어 있습니다: 그룹 변수는 빌드 시에 주입되며, 프로젝트 수준 및 환경 수준 변수는 그룹 변수보다 우선합니다.

즉, 가장 구체적인 것이 우승합니다:

환경 수준 변수, 최우선.
프로젝트 수준 변수.
그룹 변수, 최하위.

이 순서는 단순히 기술적인 세부 사항일 뿐만 아니라 실용적입니다. 그룹에서 공유 기본값을 설정하고, 그 프로젝트를 그룹에서 제거하지 않고도 다른 값이 필요한 한 프로젝트에서 이를 재정의합니다. 환경 계층은 Environment Variables Per Environment를 참조하세요.

또한 그룹에서 가장 흔한 혼동을 설명합니다: 그룹을 편집하고 재배포했는데 변경 사항이 없는 이유는 프로젝트가 조용히 같은 키를 가진 자체 변수를 가지고 있기 때문입니다. 그룹 값이 무시되는 것처럼 보일 때 먼저 프로젝트의 자체 Env vars 탭을 확인하세요.

공유 자격 증명 회전

이것이 그룹이 존재하는 워크플로우입니다:

공급자에서 새 자격 증명을 생성하고 기존 자격 증명은 활성 상태로 둡니다.
그룹의 값을 편집하고 저장합니다.
각 연결된 프로젝트를 재배포하거나 다음 배포를 기다립니다.
각 프로젝트가 새 자격 증명에서 작동하는지 확인합니다.
공급자에서 기존 자격 증명을 취소합니다.

5단계를 먼저 수행하면 모든 연결된 프로젝트가 한 번에 깨지는 기간이 생기는데, 이는 정확히 공유 자격 증명이 집중시키는 위험입니다.

그룹 삭제

그룹에서 삭제를 클릭합니다. 확인은 결과에 대해 구체적입니다: 향후 빌드에서 이러한 변수가 손실되고, 이미 완료된 빌드는 영향을 받지 않습니다.

삭제하면 모든 프로젝트의 링크도 해제됩니다. 이는 실행 중인 배포가 빌드된 값으로 계속 실행되고, 각 연결된 프로젝트의 다음 빌드가 해당 값 없이 진행됨을 의미합니다. 해당 변수가 필요하면 해당 빌드가 실패하거나 앱이 런타임에 제대로 작동하지 않을 수 있습니다.

삭제하기 전에 프로젝트를 하나씩 연결 해제하고 각각을 재배포하세요. 그러면 모든 프로젝트가 그룹을 잃기 전에 어떤 프로젝트가 실제로 그룹에 의존하는지 파악할 수 있습니다.

실용적인 조언

그룹을 작고 목적에 맞게 유지하세요. 하나의 거대한 "공유" 그룹보다 외부 서비스당 하나의 그룹이 낫습니다. 각 항목이 필요한 프로젝트를 정확히 연결할 수 있기 때문입니다.

모든 곳에서 키 이름을 동일하게 유지하세요. 한 프로젝트는 SENTRY_DSN를 읽고 다른 프로젝트는 SENTRY_KEY를 읽는다면 공유 그룹은 도움이 될 수 없습니다. 먼저 이름을 표준화하세요.

공개 미리보기가 있는 프로젝트에 연결된 그룹에 프로덕션 자격 증명을 입력하지 마세요. 그룹 변수는 연결된 프로젝트의 모든 빌드에 도달합니다. 미리보기도 포함됩니다.

문제 해결

빌드가 변수를 볼 수 없습니다. 프로젝트가 연결되고 저장되었으며, 빌드가 연결 후에 실행되었는지 확인합니다. 그룹 변수는 다음 빌드부터 적용됩니다.

런타임의 값이 잘못되었습니다. 같은 키를 가진 프로젝트 수준 또는 환경 수준 변수가 이를 재정의하고 있습니다. 프로젝트의 Env vars 탭을 확인하세요.

Create group을 사용할 수 없습니다. 20개 그룹 한계에 도달했거나 계정 역할이 소유자 또는 관리자가 아닙니다.

비밀의 값이 공백으로 표시됩니다. 이것이 맞습니다. 비밀 값은 저장 후 패널로 반환되지 않습니다.

그룹 편집 후 프로젝트가 손상되었습니다. 그룹의 값을 롤백하고 재배포한 다음, 어떤 프로젝트가 동의하지 않았는지 파악합니다. Rolling Back a Deployment은 이를 진행하는 동안 실행 중인 사이트를 건강하게 유지합니다.

다음 단계

Environment Variables in Orbit 프로젝트 수준 변수의 경우.
Environment Variables Per Environment 재정의 계층의 경우.
Orbit Project Settings 프로젝트의 나머지 구성의 경우.