시크릿: 코드에 필요한 키

#시크릿이란

시크릿은 이름이 붙은 값이에요. 값은 보통 API 키예요. 한 프로그램이 다른 프로그램과 통신할 때 쓰는 비밀번호로, 메일 발송 서비스가 주는 키가 그 예예요. 이름은 사이트 코드가 그 값을 요청할 때 쓰는 말이에요. 예를 들어 MAILING_LIST_KEY예요.

비밀 값을 읽는 사이트의 부분은 서버에서, 경로(페이지를 보여 주지 않고 코드를 실행하는 /api/ 아래 주소) 뒤에서 실행돼요. 값은 그곳에만 있어요. 사이트의 페이지에도, 방문자의 브라우저로 전송되는 내용에도, 내려받을 수 있는 코드에도 들어 있지 않아요.

한 번 저장한 값은 누구도, 본인도 다시 볼 수 없어요. 스튜디오에는 이름, 저장한 사람, 저장한 시간만 남아요. 비밀번호 관리자 같은 안전한 곳에 직접 사본을 보관해 주세요.

사이트 자체 코드가 키가 필요한 무언가와 연결될 때만 시크릿이 필요해요. 문의 양식이 있는 소개용 사이트에는 필요하지 않아요.

#시작하기 전에

• 사이트를 한 번 게시하세요. 시크릿은 게시된 사이트에만 보관되고 스튜디오에는 저장되지 않아요. 처음 게시하기 전까지는 페이지에 Publish the site first가 표시되고 아무것도 추가할 수 없어요.
• 역할을 확인하세요. Editor, Admin, Owner는 시크릿을 추가, 변경, 삭제할 수 있어요. Viewer는 이름과 저장된 시점만 볼 수 있어요.
• 이름을 정하세요. 영문자, 숫자, 밑줄을 쓸 수 있고 영문자로 시작해야 하며 최대 128자예요. 대문자와 밑줄 조합이 일반적이에요. BRIKS_로 시작하는 이름은 스튜디오용으로 예약돼 있어요.
• 한도를 확인하세요. 값은 최대 5 KB까지 가능해서 어떤 키나 인증서도 담을 수 있어요. 프로젝트 하나에 시크릿을 최대 100개까지 둘 수 있고, 스튜디오 자체 시크릿도 포함돼요.

#시크릿 추가

#.env 파일에서 여러 개 가져오기

.env 파일은 비밀 값 하나당 한 줄씩 NAME=value 형식으로 적은 일반 텍스트 파일이에요. 개발자들이 흔히 하나씩 갖고 있어요. 이 파일이 있다면 모든 줄을 한 번에 가져올 수 있어요.

#시크릿 바꾸기 또는 삭제하기

변경 사항은 바로 라이브 사이트에 반영돼요. 저장하면 The live site has it now, 삭제하면 The live site no longer has it 메시지가 보여요. 시크릿이 많으면 Search secrets 칸에서 이름으로 찾을 수 있어요. 표에는 각 시크릿의 Name과 Last saved가 저장한 사람과 함께 나와요.

일부 행에는 Managed 태그가 붙어 있어요. 스튜디오가 사이트 이메일 같은 자체 서비스를 위해 설정한 것으로, 여기서는 바꾸거나 삭제할 수 없어요.

#빌드에서 시크릿을 사용하는 방식

사이트 코드는 실행될 때마다 이름으로 시크릿을 읽기 때문에, 빌드에는 값이 필요하지 않아요. 메일링 리스트나 AI 모델처럼 다른 서비스에 사이트를 연결해 달라고 스튜디오에 요청하면, 코드는 MAILING_LIST_KEY처럼 알아보기 쉬운 이름으로 그 서비스의 키를 읽어요. 값은 여기에서 그 이름으로 추가하세요.

#빌드 전에 키를 요청받는 경우

• 게시된 사이트의 변경. 요청이 다른 서비스를 연결할 때는 잠시 동안 Checking which keys this needs라고 표시돼요. 사이트에 아직 값이 없는 키가 있으면 스튜디오가 빌드 전에 물어봐요. 대화 속 카드에는 키마다 입력란이 있고, 한 번의 변경에 최대 3개까지 나와요. 값을 붙여 넣고 Save and build를 누르면 값은 대화에 남지 않고 곧바로 사이트의 Secrets로 들어가며, 변경이 시작돼요. 값 없이 빌드하려면 Add it later를 누르세요.
• 기다리는 동안 보낸 메시지는 그 변경에 합쳐져요. 이미 저장했거나 나중에 추가하기로 한 키는 다시 묻지 않아요. 새 메시지가 다른 서비스를 연결하는 것이면, 첫 카드를 마친 뒤 그 서비스의 키만 한 번 물어봐요.
• 새 사이트. 시크릿은 게시된 사이트가 있어야 해서, 첫 빌드에서는 아직 키를 받을 수 없어요. 빌드 전 질문 중에, 지금 연결을 만들고 사이트가 게시된 뒤에 키를 추가할지, 아니면 그 부분을 일단 빼고 진행할지 물어볼 수 있어요.
• Telegram에서는 카드에 키마다 스튜디오의 Secrets를 여는 버튼이 있고, 계속하려면 Build를 눌러요. 키는 채팅으로 절대 보내지 않아요.

#사이트에 필요함

게시할 때마다 Briks는 사이트 코드가 요구하는 시크릿 이름을 읽어요. 아직 값이 없는 이름은 이 페이지 맨 위에 Needed by the site 태그와 함께 나와요. 그중 하나에서 Add value를 누르면 이름이 미리 채워진 양식이 열려요. 값이 입력되기 전에는 그 이름을 쓰는 사이트 부분이 작동하지 않아요.

빌드나 변경에 대한 답변에도 그 이름이 나와요. 예: 사이트가 MAILING_LIST_KEY를 읽는데 아직 값이 없어요: Project Settings → Secrets에서 추가하세요. 이름마다 Add MAILING_LIST_KEY 같은 버튼이 있고, 누르면 그 이름이 채워진 이 페이지가 열려요. 같은 문장이 알림에도 나오고, 빌드가 끝났을 때 Telegram으로 알려 드릴 때도 나와요.

#메시지에 붙여넣은 키

Briks는 서비스 키와 토큰의 일반적인 형태를 알아봐요. 스튜디오 채팅, 새 프로젝트의 설명, 프로젝트의 브리프, 에이전트에게 보내는 메시지나 에이전트의 지침, Visual Editor의 Ask AI, 봇과의 채팅에 키를 붙여 넣으면 메시지가 저장되거나 읽히기 전에 키가 제거되고 [key removed: add it in Settings → Secrets]로 바뀌어요. 스튜디오는 바로 알려 줘요: A key was removed from your message so it isn't stored. Add it in Project Settings → Secrets. 답장에는 이 페이지로 가는 Open Secrets 버튼이 있어요. 모든 프로젝트에서 일하는 에이전트의 스레드에서는 Open Secrets가 프로젝트 목록을 보여 주므로, 키가 속한 프로젝트를 고를 수 있어요. 에이전트가 기억해야 할 내용에 키가 들어 있으면 저장되지 않아요.

사이트를 게시하기 전에 Briks가 자체 코드에서 파일에 직접 적힌 키를 찾아봐요. 모양이 키처럼 보이는 값과, 키, 토큰, 비밀번호 같은 이름에 주어진 값이 대상이에요. 발견하면 제작을 되돌려 그 값을 빼고, 대신 이름으로 비밀 값을 읽도록 해요.

#Briks가 적용하는 보안 규칙

• 값은 암호화되어 게시된 사이트의 서버 쪽으로 바로 전달돼요. 스튜디오는 값을 보관하지 않고, 다시 보여 주지 않으며, 로그에도 남기지 않아요.
• 값은 사이트 페이지, 방문자의 브라우저, 내려받은 코드 어디에도 나타나지 않아요.
• 시크릿은 Editor, Admin, Owner만 추가, 변경, 삭제할 수 있어요.
• BRIKS_로 시작하는 이름은 스튜디오가 쓰는 것이며, 관리형 시크릿은 바꿀 수 없어요.
• 프로젝트는 1분에 시크릿을 최대 60번 변경할 수 있어요. 넘으면 이렇게 보여요: That is a lot of changes at once. Wait a minute and try again.

#시크릿이 없어졌을 때

시크릿은 사이트 주소에 속해요. 주소를 바꾸면(사이트 주소 참고) 시크릿은 이전 주소에 그대로 남아요. 스튜디오 메시지가 시크릿 목록을 알려주고 Settings, Secrets에서 다시 입력하라고 안내해요. 각 행에는 Not on the site · enter again이 표시돼요. 각각 Edit value를 선택하고 값을 붙여넣으세요.

사이트의 코드가 없는 시크릿을 요구하면 사이트의 그 부분은 Part of this site is not set up yet.라고 답해요. 이름이 대문자까지 정확히 같은지, 그리고 해당 행에 Not on the site라고 적혀 있지 않은지 확인하세요.

#활용 예시: 유출된 키 교체하기

그다음에야 메일 서비스에서 이전 키를 삭제해서, 사이트에 작동하는 키가 없는 순간이 한 번도 없었어요. 코드가 이름으로 키를 불러오기 때문에 다시 만들 필요가 없었어요.