히스토리

• GitLab 18.3에 도입 secrets_manager 및 ci_tanukey_ui 플래그와 함께. 기본적으로 비활성화됩니다.
• 기능 플래그 ci_tanukey_ui는 GitLab 18.4에서 제거됨.
• GitLab 18.8에서 일부 사용자에게 비공개 베타로 제공됩니다.
• 그룹 시크릿 관리자가 GitLab 18.10에서 도입되어 비공개 베타 사용자에게 제공됩니다. group_secrets_manager 플래그와 함께 사용됩니다.

시크릿은 CI/CD job이 작동하는 데 필요한 민감한 정보를 나타냅니다. 시크릿에는 액세스 토큰, 데이터베이스 자격 증명, 프라이빗 키 등이 포함될 수 있습니다.

기본적으로 항상 job에서 사용 가능한 CI/CD 변수와 달리 시크릿은 job에서 명시적으로 요청해야 합니다.

GitLab Secrets Manager를 사용하여 프로젝트와 그룹의 시크릿과 자격 증명을 안전하게 저장하고 관리합니다.

GitLab Secrets Manager 활성화 또는 비활성화#

프로젝트의 경우#

사전 요구 사항:

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

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > General을 선택합니다.

3. Visibility, project features, permissions를 펼칩니다.

4. Secrets manager 토글을 켜고 시크릿 관리자가 프로비저닝될 때까지 기다립니다.

   [!warning] 나중에 프로젝트에 대한 Secrets Manager를 비활성화하면 모든 프로젝트 시크릿이 영구적으로 삭제됩니다. 이 시크릿은 복구할 수 없습니다.

프로젝트에 대해 정의된 시크릿은 동일한 프로젝트의 파이프라인에서만 액세스할 수 있습니다.

그룹의 경우#

사전 요구 사항:

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

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

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Settings > General을 선택합니다.

3. Permissions and group features를 펼칩니다.

4. Secrets manager 토글을 켜고 시크릿 관리자가 프로비저닝될 때까지 기다립니다.

   [!warning] 나중에 그룹에 대한 Secrets Manager를 비활성화하면 모든 그룹 시크릿이 영구적으로 삭제됩니다. 이 시크릿은 복구할 수 없습니다.

그룹에 대해 정의된 시크릿은 해당 그룹 또는 하위 그룹 계층 구조에 속하는 프로젝트의 파이프라인에서만 액세스할 수 있습니다.

시크릿 정의#

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

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

시크릿을 생성한 후 파이프라인 구성 또는 job 스크립트에서 사용할 수 있습니다.

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

프로젝트 시크릿의 경우#

사전 요구 사항:

• GitLab Runner 18.6 이상.

시크릿 관리자로 정의된 시크릿에 액세스하려면 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"

job이 시크릿의 값을 출력하는 경우(예: cat $KUBE_CA_PEM 실행), GitLab은 job 로그에서 해당 값을 [MASKED]로 대체합니다.

그룹 시크릿의 경우#

사전 요구 사항:

• GitLab Runner 18.10 이상.

그룹 시크릿에 액세스하려면:

• secrets 및 gitlab_secrets_manager 키워드를 사용하세요.
• source 필드에 group/<그룹-전체-경로> 형식으로 시크릿 관리자 소스를 지정하세요.

예를 들어:

job:
  secrets:
    TEST_SECRET:
      gitlab_secrets_manager:
        name: foo
        source: group/<그룹-전체-경로>
  script:
   - cat $TEST_SECRET

시크릿 권한 관리#

프로젝트의 경우#

사전 요구 사항:

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

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Visibility, project features, permissions를 펼칩니다.
4. Secrets manager 아래의 Secrets manager user permissions 섹션에서 사용자 권한을 관리할 수 있습니다:
   • Add를 선택하여 특정 사용자, 그룹 또는 권한에 대한 권한 규칙을 추가합니다.
   • 시크릿 읽기, 쓰기(생성 및 업데이트), 삭제에 대한 권한 범위를 설정할 수 있습니다.

그룹의 경우#

사전 요구 사항:

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

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

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Permissions and group features를 펼칩니다.
4. Secrets manager 아래의 Secrets manager user permissions 섹션에서 사용자 권한을 관리할 수 있습니다:
   • Add를 선택하여 특정 사용자, 그룹 또는 권한에 대한 권한 규칙을 추가합니다.
   • 시크릿 읽기, 쓰기(생성 및 업데이트), 삭제에 대한 권한 범위를 설정할 수 있습니다.

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

프로젝트 또는 그룹 삭제#

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

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

프로젝트 또는 그룹 전송#

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

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

시크릿 교체 알림#

프로젝트의 Owner 권한을 가진 사용자는 시크릿 구성에 지정된 날짜에 시크릿을 교체하라는 이메일 알림을 받습니다.

트러블슈팅#

오류: 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

이 오류는 시크릿이 속해야 할 프로젝트 또는 그룹에 대한 시크릿 관리자 인스턴스가 아직 프로비저닝되지 않았을 때 발생합니다. 시크릿 관리자 역할이 아직 없기 때문에 러너가 인증을 구성할 수 없습니다.

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

프로비저닝이 완료될 때까지 기다린 후 시크릿을 생성하고 파이프라인을 다시 실행하세요.