프로젝트 빌드 시 Lovable이 주입하는 암호화된 워크스페이스 수준 환경 변수를 저장합니다.
빌드 시크릿
비공개 패키지 설치용 npm 토큰처럼 프로젝트 빌드 시 Lovable이 주입하는 암호화된 워크스페이스 수준 환경 변수를 저장하세요.
프로젝트는 앱이 실행되기 전 빌드 과정에서 인증 정보가 필요할 수 있습니다. 대표적인 예는 비공개 패키지를 설치하는 npm 토큰이며, 비공개 패키지 기반 디자인 시스템이 이에 의존합니다. 빌드 시크릿은 Lovable이 빌드 중 프로젝트에 환경 변수로 제공하는 암호화된 워크스페이스 수준 값입니다. 빌드 중 소스 맵을 업로드하는 토큰 등 다른 빌드 타임 용도로도 사용할 수 있습니다.
빌드 시크릿은 Enterprise 플랜에서 사용할 수 있습니다. 워크스페이스 소유자와 관리자가 관리하며, 편집자는 올바른 시크릿을 참조할 수 있도록 이름을 읽기 전용으로 볼 수 있습니다. 저장 후에는 누구도 값을 볼 수 없습니다.
빌드 시크릿과 앱 시크릿의 차이
Lovable에는 두 종류의 시크릿이 있으며 각각 하는 일이 다릅니다:
| 빌드 시크릿(이 페이지) | 앱 시크릿 | |
|---|---|---|
| 범위 | 모든 프로젝트가 공유하는 워크스페이스 | 프로젝트 하나 |
| 관리 위치 | Settings → Build & deploy → Build secrets | 프로젝트의 Cloud tab → Secrets |
| 사용 시점 | npm install 등 프로젝트 빌드 중 | Edge Functions 등 앱 백엔드 런타임 |
| 일반적인 값 | npm 레지스트리 토큰, 빌드 타임 CI 토큰 | Stripe 키 같은 런타임 API 키 |
앱 실행 중 키가 필요하면 앱 시크릿을 사용하고, 패키지 설치나 빌드 중 인증 정보가 필요하면 빌드 시크릿을 사용하세요.
빌드 시크릿 활용 분야
빌드 시크릿은 프로젝트가 패키지를 설치하거나 빌드할 때 필요한 모든 값을 담을 수 있습니다:
- npmjs, GitHub Packages, GitLab, Artifactory 등에서 비공개 npm 패키지 설치
- 비공개 npm 패키지를 래핑하는 디자인 시스템 연결
- 빌드 중 오류 추적기에 소스 맵을 업로드하는 도구 인증
- 워크스페이스 전체가 공유하는 다른 빌드 타임 환경 변수 제공
외부 레지스트리 인증 대신 Lovable이 레지스트리를 호스팅하게 하려면 비공개 레지스트리를 참고하세요.
빌드 시크릿 추가하기
워크스페이스 소유자와 관리자만 빌드 시크릿을 추가, 수정 또는 삭제할 수 있습니다.
Build secrets 열기
시크릿 추가하기
Add secret을 선택하고 이름과 값을 입력합니다. 프로젝트가 이 정확한 이름으로 참조하므로 NPM_TOKEN 같은 환경 변수 형식의 이름을 사용하세요. 나중에 이름을 바꿀 수 없으며 삭제 후 새로 추가해야 합니다.
저장하기
Save changes를 선택합니다. 저장 전에는 아무것도 보관되지 않으며, 저장 시점부터 값이 숨겨집니다.
워크스페이스의 모든 프로젝트는 작업 및 게시 빌드 중 빌드 시크릿을 환경 변수로 받습니다. 게시된 앱의 런타임에는 노출되지 않습니다.
비공개 npm 패키지 설치하기
비공개 레지스트리 설치를 인증하려면 프로젝트에 시크릿 이름을 참조하는 .npmrc 파일이 필요합니다. 먼저 토큰을 빌드 시크릿으로 추가하고 Lovable에 구성을 요청하세요:
Install our private package @acme/ui-components from GitHub Packages. The auth token is in the PACKAGES_TOKEN build secret.Lovable은 ${PACKAGES_TOKEN} 구문으로 시크릿을 참조하는 .npmrc를 작성합니다. GitHub Packages 예시는 다음과 같습니다:
@acme:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${PACKAGES_TOKEN}Lovable은 빌드 시크릿을 만들거나 읽을 수 없습니다. 워크스페이스 관리자가 Settings → Build & deploy → Build secrets에서 토큰을 직접 추가해야 합니다.
비공개 npm 패키지로 디자인 시스템을 만들면 설정 과정에서 레지스트리 토큰을 담은 빌드 시크릿 이름을 요청하며, 연결한 프로젝트는 이를 자동으로 사용해 인증합니다.
빌드 시크릿 업데이트 또는 삭제하기
기존 값은 항상 마스킹됩니다. 교체하려면 해당 행에 새 값을 입력하고 Save changes를 선택합니다. 삭제하려면 휴지통 아이콘을 선택하고 저장합니다.
삭제는 영구적입니다. 삭제한 값은 복구할 수 없으며, 이를 참조하는 프로젝트의 다음 빌드는 인증에 실패합니다. 삭제 전에 참조 프로젝트를 업데이트하거나 같은 이름의 대체 시크릿을 추가하세요.
제한 사항
- 빌드 시크릿은 워크스페이스 전체에 적용되며 프로젝트 하나로 범위를 제한하거나 프로젝트별로 재정의할 수 없습니다.
- 프로젝트 빌드 중에만 사용할 수 있습니다. 런타임 키는 앱 시크릿에 저장하세요.
- Lovable은 빌드 시크릿을 추가, 읽기 또는 변경할 수 없습니다. 워크스페이스 소유자나 관리자가 관리합니다.
문제 해결
빌드 시크릿이 예상대로 작동하지 않을 때 가장 흔한 원인은 다음과 같습니다:
FAQ
빌드 시크릿의 동작에 관해 자주 묻는 질문입니다: