히스토리

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

GitLab Secrets Manager를 사용해 OpenBao를 기반으로 프로젝트와 그룹의 자격 증명을 안전하게 암호화, 저장, 조회합니다. 자격 증명을 코드에 직접 입력하거나 CI/CD 변수에 의존하는 대신, GitLab 액세스 모델과 감사 시스템을 사용해 완전한 감사 추적과 함께 시크릿을 조회할 수 있습니다.

시크릿은 CI/CD job이 작동하는 데 필요한 민감한 정보를 나타내며, 액세스 토큰, 데이터베이스 자격 증명, 프라이빗 키 등이 해당합니다. 기본적으로 항상 job에서 사용할 수 있는 CI/CD 변수와 달리, 시크릿은 job이 명시적으로 요청해야 합니다.

CI/CD job에서 시크릿을 사용하거나 Kubernetes, Terraform, API 같은 CI/CD 밖의 런타임 워크로드에서 사용할 수 있습니다.

GitLab Secrets Manager는 GitLab 크레딧을 소비합니다.

피드백은 이슈 598100에서 공유해 주시기 바랍니다.

GitLab Secrets Manager 활성화#

GitLab.com에서는 최상위 그룹에 대해 GitLab Secrets Manager를 활성화합니다. 그러면 해당 그룹의 모든 하위 그룹과 프로젝트에서 Secrets Manager를 사용할 수 있습니다.

GitLab Self-Managed에서는 관리자가 인스턴스에 대해 Secrets Manager를 활성화합니다. 그러면 인스턴스의 모든 그룹과 프로젝트에서 Secrets Manager를 사용할 수 있습니다.

Secrets Manager가 활성화되면 해당 그룹과 프로젝트 어디에서든 시크릿을 생성할 수 있습니다.

GitLab.com의 경우#

GitLab 크레딧으로 활성화#

히스토리

• Enable with GitLab Credits 옵션이 GitLab 19.4에서 도입되었습니다.

사전 요구 사항:

• 최상위 그룹에 대해 Owner 권한이 있어야 합니다.

GitLab 크레딧으로 GitLab Secrets Manager를 활성화하려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Secure > Secrets manager를 선택합니다.
3. Enable with GitLab Credits를 선택합니다.
4. 확인 대화 상자에서 Enable GitLab Secrets Manager를 선택합니다.

구독에 사용 가능한 GitLab 크레딧이 없으면, 구독 소유자가 먼저 월간 커밋을 구매하거나 Customers Portal에서 온디맨드 결제를 수락해야 합니다.

트라이얼 시작#

또는 30일 트라이얼을 시작해 임시 평가 크레딧으로 GitLab Secrets Manager를 사용해 볼 수 있습니다. 트라이얼이 만료되면 GitLab Secrets Manager는 GitLab 크레딧을 소비하기 시작합니다. 서비스 중단을 방지하려면 트라이얼이 끝나기 전에 월간 크레딧 커밋 풀을 구매하거나 사용량 결제 약관에 동의합니다.

GitLab Self-Managed의 경우#

관리자만 Secrets Manager를 활성화하거나 비활성화할 수 있으며, 이 설정은 인스턴스 전체에 적용됩니다. Secrets Manager가 활성화되기 전에는 왼쪽 사이드바에 Secrets manager 항목이 표시되지 않습니다.

인스턴스에 대해 GitLab Secrets Manager를 활성화하면 인스턴스의 모든 그룹과 프로젝트에서 Secrets Manager를 사용할 수 있습니다.

사전 요구 사항:

• 관리자 액세스 권한.
• OpenBao를 설치하고 구성해야 합니다.
• Premium 또는 Ultimate 구독이 있어야 합니다.

온라인 라이선스에서는 트라이얼을 시작하거나 GitLab 크레딧으로 활성화할 수 있습니다. 인스턴스가 오프라인 라이선스를 사용한다면 오프라인 라이선스로 활성화를 참고합니다.

트라이얼 시작#

트라이얼 크레딧, 트라이얼 종료 시점, 트라이얼 시작 단계는 GitLab Self-Managed에서 트라이얼 시작을 참고합니다.

GitLab 크레딧으로 활성화#

사전 요구 사항:

• 인스턴스에 온라인 클라우드 라이선스가 있어야 합니다.
• 구독에 월간 커밋 또는 Customers Portal에서 수락한 온디맨드 결제를 통해 사용 가능한 GitLab 크레딧이 있어야 합니다.

GitLab 크레딧으로 GitLab Secrets Manager를 활성화하려면 다음을 수행합니다.

1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. GitLab Secrets Manager를 펼칩니다.
4. Enable with GitLab Credits를 선택합니다.
5. 확인 대화 상자에서 Enable GitLab Secrets Manager를 선택합니다.

오프라인 라이선스로 활성화#

오프라인 인스턴스는 트라이얼을 시작하거나 Enable with GitLab Credits를 사용할 수 없습니다. 대신 Secrets Manager 토글을 켭니다.

오프라인 라이선스에 GitLab Secrets Manager가 포함되어 있어야 합니다.

GitLab Secrets Manager를 활성화하려면 다음을 수행합니다.

1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. GitLab Secrets Manager를 펼칩니다.
4. Secrets Manager 토글을 켭니다.

라이선스에 GitLab Secrets Manager가 포함되어 있지 않으면 토글이 비활성화되고 해당 섹션에 경고가 표시됩니다. 라이선스를 구매하려면 구독 소유자에게 문의합니다.

시크릿 정의#

안전한 CI/CD 파이프라인과 워크플로에 사용할 수 있도록 시크릿 관리자에 시크릿을 추가할 수 있습니다.

프로젝트에 정의된 시크릿은 동일한 프로젝트의 파이프라인에서만 접근할 수 있습니다. 그룹에 정의된 시크릿은 해당 그룹 바로 아래의 프로젝트 또는 그 하위 그룹 계층 구조의 프로젝트에 있는 파이프라인에서만 접근할 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트나 그룹을 찾습니다.
2. Secure > Secrets manager를 선택합니다.
3. New secret을 선택하고 세부 정보를 입력합니다.
   • Name: 생성하는 프로젝트나 그룹 내에서 고유해야 하며, 255자 이하여야 하고, 영문자, 숫자, 밑줄(_)만 포함할 수 있습니다. 시크릿을 생성한 후에는 이름을 변경할 수 없습니다.
   • Value: 10 KB(10,000바이트) 이하여야 합니다.
   • Description: 최대 200자입니다.
   • Environments: 다음 중 하나일 수 있습니다.
     • All (default) (*)
     • 특정 환경.
     • 와일드카드 환경.
   • Branches: 프로젝트 설정에만 존재하는 옵션입니다. 다음 중 하나일 수 있습니다.
     • 특정 브랜치.
     • 와일드카드 브랜치(* 문자를 포함해야 함).
   • Protected Branches: 그룹 설정에만 존재하는 옵션입니다. 선택 사항입니다. 보호된 브랜치에서 실행되는 파이프라인에만 시크릿을 내보냅니다.
   • Rotation reminder period: 선택 사항입니다. 설정된 일수가 지난 후 시크릿을 교체하라는 이메일 알림을 보냅니다. 최소 7일입니다.
4. Add secret을 선택합니다.

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

시크릿을 생성한 후에는 다음을 수행할 수 있습니다.

• 파이프라인 설정이나 job 스크립트에서 사용할 수 있습니다.
• 시크릿을 수정하는 경우, 값을 새로운 값으로 덮어쓰기만 할 수 있습니다. UI를 통해 시크릿 값을 조회할 수는 없습니다. 자세한 내용은 GitLab Secrets Manager 권한을 참고합니다.

job 스크립트에서 시크릿 사용#

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

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

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

job이 시크릿의 값을 출력하면, GitLab은 job 로그에서 해당 값을 [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 키워드를 사용합니다.
• group/ 접두사와 <full-path-to-group>을 붙인 source 필드를 사용하여 그룹을 시크릿 관리자 소스로 지정합니다.

예를 들면 다음과 같습니다.

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 변수로 job에서 사용할 수 있으며, 다른 환경 변수와 마찬가지로 사용할 수 있습니다.

시크릿 교체 알림#

프로젝트에 대해 Owner 권한이 있는 사용자는 시크릿 설정에 지정된 날짜에 시크릿을 교체하라는 이메일 알림을 받습니다.

CI/CD가 아닌 워크로드에서 시크릿 접근#

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

시크릿 권한 관리#

프로젝트의 경우#

사전 요구 사항:

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

프로젝트의 시크릿 권한을 업데이트하려면 다음을 수행합니다.

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

GitLab 19.4 이상에서 활성화된 시크릿 관리자의 경우, 프로젝트에 대해 Maintainer 권한이 있는 사용자는 기본적으로 읽기 및 쓰기(생성 및 업데이트) 권한을 갖습니다.

프로젝트에 대해 Developer 권한이 있는 사용자는 기본적으로 메타데이터 읽기 및 생성 권한을 갖습니다. 생성 권한에는 업데이트가 포함되지 않으므로, 이러한 사용자는 시크릿을 추가할 수 있지만 이미 존재하는 시크릿은 변경할 수 없습니다.

Owner 권한이 있는 사용자는 이러한 기본 권한을 제거하거나 변경할 수 있습니다.

그룹의 경우#

히스토리

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

사전 요구 사항:

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

그룹의 시크릿 권한을 업데이트하려면 다음을 수행합니다.

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

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

프로젝트나 그룹 삭제#

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

• 해당 프로젝트나 그룹의 시크릿 관리자가 비활성화되고 시크릿 스토리지 엔진에서 제거됩니다.
• 모든 시크릿이 영구적으로 삭제됩니다.

프로젝트나 그룹 이전#

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

• 해당 프로젝트나 그룹에 정의된 시크릿은 새 네임스페이스의 프로젝트나 그룹으로 이전되지 않습니다.
• 해당 프로젝트나 그룹의 시크릿 관리자가 비활성화되고 시크릿 스토리지 엔진에서 제거됩니다.
• 모든 시크릿이 영구적으로 삭제됩니다.

GitLab Secrets Manager 비활성화#

GitLab Secrets Manager를 비활성화하면 다음과 같이 됩니다.

• 시크릿을 가져오는 job이나 워크로드가 작동을 멈춥니다.
• GitLab은 시크릿을 삭제하지 않습니다.
• 프로젝트 및 그룹 멤버는 기존 시크릿의 세부 정보를 보거나 삭제하는 것만 할 수 있습니다.
• Secrets Manager는 GitLab 크레딧을 소비하지 않습니다.

트라이얼을 시작했다면 트라이얼이 끝나기 전에는 언제든 Secrets Manager를 다시 활성화할 수 있습니다.

GitLab.com에서 비활성화#

사전 요구 사항:

• 최상위 그룹에 대해 Owner 권한이 있어야 합니다.

GitLab Secrets Manager를 비활성화하려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Secure를 선택합니다.
3. GitLab Secrets Manager 섹션에서 토글을 끕니다.
4. 확인 대화 상자에서 Disable을 선택합니다.

Secrets Manager를 다시 활성화하려면 토글을 다시 켭니다.

GitLab Self-Managed에서 비활성화#

Secrets Manager를 비활성화하면 인스턴스의 모든 그룹과 프로젝트에 적용됩니다. 애드온이 포함된 오프라인 라이선스에서는 GitLab이 Secrets Manager에 대한 결제를 중단합니다.

사전 요구 사항:

• 관리자 액세스 권한.

GitLab Secrets Manager를 비활성화하려면 다음을 수행합니다.

1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. GitLab Secrets Manager를 펼칩니다.
4. Secrets Manager 토글을 끕니다.
5. 확인 대화 상자에서 Disable을 선택합니다.

관련 주제#

• GitLab Secrets Manager 크레딧 사용량
• Secret Audit Tool for Variables: 이름에 자격 증명(비밀번호, 토큰, API 키 등)을 담고 있을 것으로 추정되는 CI/CD 변수를 GitLab 그룹 계층 구조 전체에서 스캔하는 커뮤니티 도구입니다. GitLab Secrets Manager로 마이그레이션할 변수를 식별하는 데 도움이 되는 HTML 리포트를 생성합니다.

문제 해결#

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

CI/CD 파이프라인 job이 시크릿을 가져오려고 시도할 때 다음 오류가 반환될 수 있습니다.

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

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

오류: inline auth JWT is required#

CI/CD 파이프라인 job이 시크릿을 가져오려고 시도할 때 다음 오류가 반환될 수 있습니다.

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

이 오류는 시크릿이 속할 것으로 예상되는 프로젝트나 그룹에 대해 시크릿 관리자 인스턴스가 아직 프로비저닝되지 않은 경우 발생합니다. 아직 시크릿 관리자 역할이 존재하지 않으므로 러너가 인증을 구성할 수 없습니다.

이 오류를 해결하려면 프로젝트나 그룹에 시크릿을 생성합니다. 그런 다음 파이프라인을 다시 실행합니다.

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

네임스페이스가 GitLab Secrets Manager에 접근할 수 없는 경우, GitLab Secrets Manager에 시크릿을 요청하는 job은 러너가 이를 가져가기 전에 이 오류와 함께 실패합니다.

GitLab.com#

GitLab.com에서 발생 가능한 원인:

• 트라이얼이 만료되었습니다.
• 그룹에 사용 가능한 GitLab 크레딧이 없습니다.
• 온디맨드 결제가 꺼져 있습니다.
• 구독 유예 기간이 만료되었습니다.
• 공개 베타가 종료되었고 네임스페이스가 참여하지 않았습니다.

최상위 그룹의 접근을 복구하려면, 무료 트라이얼을 시작하거나 GitLab 크레딧으로 GitLab Secrets Manager를 활성화합니다. 구독에 월간 커밋 또는 온디맨드 결제를 통해 사용 가능한 GitLab 크레딧이 있어야 합니다. 구독이 만료된 경우 갱신합니다. 자세한 내용은 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를 추가해 달라고 요청합니다. 유료 구독이 있는 인스턴스는 무료 트라이얼도 시작할 수 있습니다.