GitLab Secrets Manager

프로젝트나 그룹의 시크릿과 자격 증명을 안전하게 저장하고 관리하고 싶다면 GitLab Secrets Manager를 사용해요. 시크릿은 CI/CD 잡이 동작하는 데 필요한 민감한 정보(접근 토큰, 데이터베이스 자격 증명, 프라이빗 키 등)를 말합니다. CI/CD 변수와 달리 시크릿은 잡이 명시적으로 요청해야만 사용할 수 있다는 점이 특징이에요.

출처: 문서

본문

GitLab 18.3에서 기능 플래그 secrets_manager와 ci_tanukey_ui와 함께 도입되었습니다. 기본적으로 비활성화되어 있어요.
기능 플래그 ci_tanukey_ui는 GitLab 18.4에서 제거되었습니다.
GitLab 18.8에서 일부 사용자에게 클로즈드 베타로 제공되었습니다.
그룹 secrets manager는 18.10에서 기능 플래그 group_secrets_manager와 함께 도입되어 클로즈드 베타 사용자에게 제공됐습니다.
GitLab 19.0에서 클로즈드 베타에서 공개 베타로 변경되었습니다.
GitLab 19.3에서 GitLab.com에서 제한적 사용 가능으로 변경되었습니다.
프로젝트에서 Maintainer 역할의 기본 읽기·쓰기 권한이 GitLab 19.4에서 도입되었습니다.
그룹에 대한 시크릿 권한이 GitLab 19.4에서 제거되었습니다. 그룹 권한은 더 이상 접근을 부여하지 않으며, GROUP principal 유형, PrincipalInput의 groupPath 인자, Principal의 group 필드가 GraphQL API에서 제거됐습니다. 대신 사용자나 역할에 권한을 부여하세요.

GitLab Secrets Manager를 사용해 프로젝트와 그룹의 시크릿 및 자격 증명을 안전하게 저장하고 관리하세요.

시크릿은 CI/CD 잡이 동작하는 데 필요한 민감한 정보를 나타냅니다. 시크릿은 접근 토큰, 데이터베이스 자격 증명, 프라이빗 키 등일 수 있어요. 기본적으로 잡에 항상 제공되는 CI/CD 변수와 달리, 시크릿은 잡이 명시적으로 요청해야 합니다.

GitLab Secrets Manager는 GitLab Credits를 소비합니다.

공개 베타 중 의견은 피드백 이슈 598100에 남겨 주세요.

GitLab Secrets Manager 활성화하기

최상위 그룹에 Secrets Manager가 활성화되면, 그 그룹의 모든 하위 그룹과 프로젝트에서도 사용할 수 있어요.

GitLab Self-Managed에서는 관리자가 먼저 인스턴스에 GitLab Secrets Manager를 설치하고 활성화해야 합니다. 설치되고 활성화된 후에 인스턴스의 특정 그룹과 프로젝트에 대해 활성화할 수 있어요.

GitLab.com의 경우

임시 평가 크레딧으로 GitLab Secrets Manager를 시도해 볼 수 있는 30일 트라이얼을 시작할 수 있어요. 트라이얼이 만료된 후에는 GitLab Secrets Manager가 GitLab 크레딧을 소비하기 시작합니다. 서비스 중단을 피하려면 트라이얼이 끝나기 전에 월간 약정 풀 크레딧을 구매하거나 온디맨드 결제를 활성화하세요. 자세한 내용은 GitLab Secrets Manager 크레딧 사용량을 참고하세요.
2026년 8월 21일 이전에 베타에 참여했다면, 2026년 9월 21일까지 지속되는 접근 유예 기간이 있어요. 유예 기간 이후에는 GitLab이 접근을 비활성화합니다. 계속 사용하려면 유예 기간이 끝나기 전에 트라이얼을 시작하세요.

전제 조건:

최상위 그룹에 대한 Owner 역할이 있어야 합니다.

상단 바에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.
왼쪽 사이드바에서 Secure > Secrets Manager를 선택하세요.
Start 30-day trial을 선택합니다.

GitLab Self-Managed의 경우

GitLab Secrets Manager는 공개 베타 동안 무료입니다. GitLab은 일반 공개 전에 알려 주므로, 크레딧 트라이얼을 시작하거나 온디맨드 결제에 참여할 시간을 가질 수 있어요.

프로젝트의 경우

전제 조건:

프로젝트에 대한 Owner 역할이 있어야 합니다.

프로젝트에 대해 GitLab Secrets Manager를 활성화하거나 비활성화하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > General을 선택하세요.
Visibility, project features, permissions을 펼칩니다.
GitLab Secrets Manager 토글을 켜고 secrets manager가 프로비저닝될 때까지 기다립니다. 나중에 프로젝트에 대해 Secrets Manager를 비활성화하면 프로젝트의 모든 시크릿이 영구 삭제됩니다. 이 시크릿들은 복구할 수 없어요.

프로젝트에 정의된 시크릿은 같은 프로젝트의 파이프라인만 접근할 수 있습니다.

그룹의 경우

최상위 그룹 설정이 GitLab 19.4에서 Settings > General에서 Settings > Secure로 이동되었습니다.

전제 조건:

그룹에 대한 Owner 역할이 있어야 합니다.

그룹에 대해 GitLab Secrets Manager를 활성화하거나 비활성화하려면:

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
왼쪽 사이드바에서: 최상위 그룹이면 Settings > Secure를, 하위 그룹이면 Settings > General을 선택하고 Permissions and group features를 펼칩니다.
GitLab Secrets Manager 토글을 켜고 secrets manager가 프로비저닝될 때까지 기다립니다. 나중에 그룹에 대해 Secrets Manager를 비활성화하면 그룹의 모든 시크릿이 영구 삭제됩니다. 이 시크릿들은 복구할 수 없어요.

그룹에 정의된 시크릿은 그룹 바로 아래의 프로젝트나 그 하위 그룹 계층에 있는 프로젝트의 파이프라인만 접근할 수 있습니다.

시크릿 정의하기

안전한 CI/CD 파이프라인과 워크플로에 사용할 수 있도록 secrets manager에 시크릿을 추가할 수 있어요.

상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.
Secure > Secrets manager를 선택하세요.
Add secret을 선택하고 세부 정보를 채웁니다.

Name: 프로젝트에서 고유해야 합니다.
Value: 10 KB(10,000바이트) 이하여야 합니다.
Description: 최대 200자.
Environments: All(기본값)(*), 특정 환경, 와일드카드 환경이 될 수 있어요.
Branch: 프로젝트 설정에만 있는 옵션입니다. 특정 브랜치 또는 와일드카드 브랜치(* 문자 포함 필수)가 될 수 있어요.
Protected: 그룹 설정에만 있는 옵션입니다. 선택 사항으로, 보호된 브랜치에서 실행되는 파이프라인에만 시크릿을 내보냅니다.
Rotation reminder: 선택 사항입니다. 설정한 일수가 지나면 시크릿을 회전하라는 이메일 알림을 보냅니다. 최소 7일.

기본적으로 프로젝트당 최대 100개, 그룹당 최대 500개 시크릿을 저장할 수 있어요. 하위 그룹이나 멤버 프로젝트의 시크릿은 상위 그룹의 제한에 집계되지 않습니다.

시크릿을 만든 후에는:

파이프라인 구성이나 잡 스크립트에서 사용할 수 있어요.
시크릿을 편집하면 값만 새 값으로 덮어쓸 수 있습니다. UI를 통해 시크릿 값을 조회할 수는 없어요. 자세한 내용은 GitLab Secrets Manager 권한을 참고하세요.

시크릿의 값은 시크릿이 생성되거나 업데이트될 때 정의된 특정 환경 또는 브랜치에 대해 실행되는 모든 CI/CD 파이프라인 잡이 접근할 수 있습니다. 이 시크릿 값에 접근 권한이 있는 사용자만 지정된 환경 또는 브랜치에 대한 잡을 실행할 수 있게 하세요.

잡 스크립트에서 시크릿 사용하기

기본적으로 파일 타입 CI/CD 변수와 유사하게, 시크릿은 관련 환경 변수와 함께 파일로 잡에서 사용할 수 있게 됩니다.

시크릿의 키는 환경 변수 이름입니다.
시크릿의 값은 임시 파일에 저장됩니다. 마스킹된 CI/CD 변수와 달리 시크릿은 공백과 줄바꿈을 가질 수 있어요.
임시 파일의 경로가 환경 변수 값입니다.

잡 스크립트에서 파일을 입력으로 받는 명령과 함께 시크릿을 사용하거나, 선택 사항으로 시크릿을 환경 변수로 직접 사용할 수 있습니다.

잡이 시크릿 값을 출력하면 GitLab이 잡 로그의 값을 [MASKED]로 대체합니다.

프로젝트 시크릿의 경우

전제 조건:

GitLab Runner 19.0 이상.

프로젝트의 Secret Manager에 저장된 시크릿에 접근하려면 secrets와 gitlab_secrets_manager 키워드를 사용하세요.

예를 들어:

job:
  secrets:
    KUBE_CA_PEM:
      gitlab_secrets_manager:
        name: kube_cert
  script:
   - kubectl config set-cluster e2e --server="https://example.com" --certificate-authority="$KUBE_CA_PEM"

그룹 시크릿의 경우

전제 조건:

GitLab Runner 19.0 이상.

그룹의 Secret Manager에 저장된 시크릿에 접근하려면:

secrets와 gitlab_secrets_manager 키워드를 사용합니다.
source 필드에 group/ 접두사 뒤에 <full-path-to-group>을 붙여 시크릿 매니저 소스로 그룹을 지정합니다.

예를 들어:

job:
  secrets:
    KUBE_CA_PEM:
      gitlab_secrets_manager:
        name: kube_cert
        source: group/my-group/my-subgroup
  script:
   - kubectl config set-cluster e2e --server="https://example.com" --certificate-authority="$KUBE_CA_PEM"

`file: false`로 시크릿을 환경 변수로 사용

시크릿을 환경 변수로 사용하고 파일에 저장하지 않으려면 시크릿에 file: false를 설정하세요. 예를 들어:

job:
  secrets:
    DEPLOY_SECRET:
      gitlab_secrets_manager:
        name: deploy_credentials
      file: false
  script:
    - my_deploy_command --user username --pass $DEPLOY_SECRET

이 예시에서 시크릿은 DEPLOY_SECRET 변수로 잡에 제공되며, 다른 환경 변수처럼 사용할 수 있어요.

시크릿 권한 관리

프로젝트의 경우

전제 조건:

시크릿 권한을 관리하려면 프로젝트에 대한 Owner 역할이 있어야 합니다.
프로젝트에 Maintainer 역할이 있는 사용자는 정의된 권한을 볼 수 있어요.
프로젝트에 대해 Secrets Manager가 활성화되어 있어야 합니다.

프로젝트의 시크릿 권한을 업데이트하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > General을 선택하세요.
Visibility, project features, permissions을 펼칩니다.
GitLab Secrets Manager 아래 User permissions 섹션에서: Add를 선택해 특정 사용자나 역할에 대한 권한 규칙을 추가합니다. 권한 범위를 메타데이터 읽기, 값 읽기, 쓰기(생성 및 업데이트), 시크릿 삭제로 설정할 수 있어요.

GitLab 19.4 이상에서 활성화된 secrets manager의 경우, 프로젝트에 Maintainer 역할이 있는 사용자는 기본적으로 읽기와 쓰기(생성 및 업데이트) 권한을 가집니다. Owner 역할이 있는 사용자는 이 기본 권한을 제거하거나 변경할 수 있어요.

그룹의 경우

최상위 그룹 설정이 GitLab 19.4에서 Settings > General에서 Settings > Secure로 이동되었습니다.

전제 조건:

시크릿 권한을 관리하려면 그룹에 대한 Owner 역할이 있어야 합니다. 그룹에 Owner 역할이 있는 사용자만 정의된 권한을 볼 수 있어요.
그룹에 대해 Secrets Manager가 활성화되어 있어야 합니다.

그룹의 시크릿 권한을 업데이트하려면:

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
왼쪽 사이드바에서: 최상위 그룹이면 Settings > Secure를, 하위 그룹이면 Settings > General을 선택하고 Permissions and group features를 펼칩니다.
GitLab Secrets Manager 아래 User permissions 섹션에서: Add를 선택해 특정 사용자나 역할에 대한 권한 규칙을 추가합니다. 권한 범위를 메타데이터 읽기, 값 읽기, 쓰기(생성 및 업데이트), 시크릿 삭제로 설정할 수 있어요.

그룹에 Owner 역할이 있는 사용자는 항상 Secrets Manager에서 모든 작업을 수행할 권한을 가집니다.

프로젝트 또는 그룹 삭제

시크릿이 있는 프로젝트를 삭제하거나 그룹을 삭제하면:

프로젝트 또는 그룹의 secrets manager가 비활성화되고 시크릿 저장 엔진에서 제거됩니다.
모든 시크릿이 영구 삭제됩니다.

프로젝트 또는 그룹 이전

시크릿이 있는 프로젝트를 이전하거나 그룹을 이전하면:

프로젝트 또는 그룹에 정의된 시크릿은 새 네임스페이스의 프로젝트나 그룹으로 이전되지 않습니다.
프로젝트 또는 그룹의 secrets manager가 비활성화되고 시크릿 저장 엔진에서 제거됩니다.
모든 시크릿이 영구 삭제됩니다.

시크릿 회전 알림

프로젝트에서 Owner 역할이 있는 사용자는 시크릿 구성에 지정된 날짜에 시크릿을 회전하라는 이메일 알림을 받습니다.

비-CI/CD 워크로드에서 시크릿 접근

GitLab CI/CD 잡으로 실행되지 않는 워크로드는 Secrets Manager API를 통해 시크릿을 읽을 수 있습니다. 자세한 내용은 비-CI/CD 워크로드에서 시크릿 접근을 참고하세요.

문제 해결

오류: `reading from Vault: api error: status code 403`

CI/CD 파이프라인 잡이 시크릿을 가져오려고 할 때 이 오류를 반환할 수 있어요.

ERROR: Job failed (system failure): resolving secrets: getting secret: get secret data: reading from Vault: api error: status code 403: 1 error occurred: * permission denied

이 오류는 잡이 존재하지 않거나 삭제된 시크릿을 가져오려고 할 때 발생합니다.

오류: `inline auth JWT is required`

CI/CD 파이프라인 잡이 시크릿을 가져오려고 할 때 이 오류를 반환할 수 있어요.

ERROR: Job failed (system failure): resolving secrets: creating vault client: configuring inline auth: inline auth JWT is required

이 오류는 시크릿이 속할 것으로 예상되는 프로젝트나 그룹에 대해 secrets manager 인스턴스가 아직 프로비저닝되지 않았을 때 발생합니다. 아직 secrets manager 역할이 없어 러너가 인증을 구성할 수 없어요.

이 오류를 해결하려면 프로젝트나 그룹에 대해 Secrets Manager를 활성화하세요.

프로비저닝이 완료될 때까지 기다렸다가 시크릿을 만든 후 파이프라인을 다시 실행하세요.

오류: `namespace does not have access to GitLab Secrets Manager`

네임스페이스가 GitLab Secrets Manager에 접근할 수 없을 때, Secrets Manager로부터 시크릿을 요청하는 잡은 러너가 집기 전에 이 오류로 실패합니다.

GitLab.com

GitLab.com에서 가능한 원인:

트라이얼이 만료됨.
그룹에 GitLab 크레딧이 없음.
온디맨드 결제가 꺼져 있음.
구독 유예 기간이 만료됨.
공개 베타가 끝났고 네임스페이스가 참여하지 않음.

최상위 그룹의 접근을 복원하려면 무료 트라이얼을 시작하거나 Secrets Manager의 온디맨드 결제를 활성화하세요. 구독이 만료되면 갱신하세요. 자세한 내용은 GitLab Secrets Manager 사용량과 결제를 참고하세요.

GitLab Self-Managed

GitLab Self-Managed에서는 GitLab이 Secrets Manager 접근을 그룹별이 아니라 인스턴스 수준에서 해결합니다.

가능한 원인:

인스턴스가 트라이얼 라이선스를 사용 중. Secrets Manager 트라이얼은 유료 구독에서만 사용할 수 있어요.
Secrets Manager 트라이얼이 만료됨.
인스턴스 구독에 GitLab Secrets Manager가 포함되지 않음.
구독 유예 기간이 만료됨.
오프라인 라이선스의 경우 라이선스에 활성 GitLab Secrets Manager 애드온이 포함되지 않음.

접근을 복원하려면 인스턴스 관리자에게 인스턴스 구독에 GitLab Secrets Manager를 추가하도록 요청하세요. 유료 구독이 있는 인스턴스는 무료 트라이얼도 시작할 수 있어요.

더 알아보기

Secrets Manager는 CI/CD 변수와 달리 잡이 명시적으로 요청해야 값을 사용할 수 있고, UI로 값을 다시 조회할 수 없다는 점이 핵심이에요. 프로젝트·그룹 단위로 활성화하고 secrets와 gitlab_secrets_manager 키워드로 잡에 연결합니다. 비용을 계산하고 싶다면 크레딧 사용량 문서를, 쿠버네티스 같은 외부 워크로드 연동은 비-CI/CD 접근 문서를 이어서 보면 좋아요.

GitLab Secrets Manager

GitLab Secrets Manager

본문

GitLab Secrets Manager 활성화하기

GitLab.com의 경우

GitLab Self-Managed의 경우

프로젝트의 경우

그룹의 경우

시크릿 정의하기

잡 스크립트에서 시크릿 사용하기

프로젝트 시크릿의 경우

그룹 시크릿의 경우

file: false로 시크릿을 환경 변수로 사용

시크릿 권한 관리

프로젝트의 경우

그룹의 경우

프로젝트 또는 그룹 삭제

프로젝트 또는 그룹 이전

시크릿 회전 알림

비-CI/CD 워크로드에서 시크릿 접근

관련 주제

문제 해결

오류: reading from Vault: api error: status code 403

오류: inline auth JWT is required

오류: namespace does not have access to GitLab Secrets Manager

GitLab.com

GitLab Self-Managed

더 알아보기

`file: false`로 시크릿을 환경 변수로 사용

오류: `reading from Vault: api error: status code 403`

오류: `inline auth JWT is required`

오류: `namespace does not have access to GitLab Secrets Manager`