비밀 푸시 보호

Tier: Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 16.7에서 GitLab Dedicated 고객을 위한 실험으로 도입됨.
  • GitLab 17.1에서 Beta로 변경되어 GitLab.com에서 제공됨.
  • GitLab 17.2에서 self-managed에 pre_receive_secret_detection_beta_release 및 pre_receive_secret_detection_push_check라는 플래그와 함께 활성화됨.
  • GitLab 17.4에서 pre_receive_secret_detection_beta_release 기능 플래그가 제거됨.
  • GitLab 17.5에서 일반적으로 사용 가능.

self-managed GitLab에서는 기본적으로 이 기능이 제공됩니다. 기능을 숨기려면
관리자에게 pre_receive_secret_detection_push_check라는 기능 플래그를 비활성화해 달라고 요청하세요.

비밀 푸시 보호는 API 토큰 및 키와 같은 비밀이 GitLab에 푸시되는 것을 차단합니다.
각 커밋의 내용을 GitLab에 푸시할 때 비밀이 있는지 확인합니다. 비밀이 감지되면 푸시가 차단됩니다.

비밀 푸시 보호와 함께 파이프라인 비밀 감지를 사용하여 보안을 강화하세요.


개요는 Get Started with Secret Push Protection 재생목록을 참조하세요.

Git 클라이언트에 관계없이 GitLab은 푸시가 차단될 때 메시지를 표시하며, 해당 메시지에는 다음 세부정보가 포함됩니다:

  • 비밀이 포함된 커밋 ID.
  • 비밀이 포함된 파일 이름 및 줄.
  • 비밀의 유형.

예를 들어, Git CLI를 사용하여 푸시가 차단될 때 반환되는 메시지의 일부는 다음과 같습니다.
다른 클라이언트를 사용할 때, GitLab Web IDE 포함 형식은 다르지만 내용은 동일합니다.

remote: PUSH BLOCKED: Secrets detected in code changes  
remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6  
remote:  
remote: -- test.txt:2 GitLab Personal Access Token  
remote:  
remote: To push your changes you must remove the identified secrets.

비밀 푸시 보호가 커밋에서 비밀을 감지하지 못하면 메시지가 표시되지 않습니다.

감지된 비밀

GitLab은 GitLab에 푸시되는 비밀을 차단하는 데 사용되는 규칙 집합을 유지 관리합니다.

낮은 신뢰도 패턴에 대한 스캔은 잠재적으로 타임아웃이나 푸시 체크 실패로 이어질 수 있습니다.
따라서 코드 푸시 시 성능 저하 없이 비공식 경고를 줄이기 위해 높은 신뢰도 패턴만 포함하기로 결정했습니다.

현재 비밀 푸시 보호와 함께 사용자 지정 규칙 집합을 사용하는 것은 불가능합니다.

비밀 푸시 보호 활성화

GitLab 전용 및 자체 관리 인스턴스에서는 전체 인스턴스에 대해 비밀 푸시 보호를 활성화해야 하며, 이후 프로젝트별로 활성화해야 합니다.

GitLab.com에서는 이 설정이 전체 인스턴스에 대해 활성화되어 있습니다. 프로젝트별로 활성화해야 합니다.

GitLab 인스턴스에서 비밀 푸시 보호 사용 허용

참고: 이 옵션을 설정하면 GitLab 인스턴스의 프로젝트에서 비밀 푸시 보호를 활성화할 수 있는 권한이 부여됩니다.

비밀 푸시 보호를 사용하려면 각 프로젝트에서도 활성화해야 합니다. 자세한 내용은 프로젝트에서 비밀 푸시 보호 활성화를 참조하세요.

필수 조건:

  • GitLab 인스턴스에 대한 관리자가 되어야 합니다.
  1. 관리자로 GitLab 인스턴스에 로그인합니다.
  2. 왼쪽 사이드바에서 하단의 Admin을 선택합니다.
  3. Settings > Security and compliance를 선택합니다.
  4. Secret detection에서 Allow secret push protection을 선택하거나 선택 해제합니다.

프로젝트에서 비밀 푸시 보호 활성화

필수 조건:

  • 프로젝트에 대해 최소한 유지 관리자(Maintainer) 역할을 가져야 합니다.

프로젝트에서 비밀 푸시 보호를 활성화하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. 왼쪽 사이드바에서 Secure > Security configuration을 선택합니다.
  3. Secret push protection 토글을 켭니다.

적용 범위

비밀 푸시 보호는 커밋이 GitLab에 푸시될 때 각 커밋의 내용을 검사합니다.

그러나 다음 조건이 적용됩니다:

비밀 푸시 보호는 다음 중 하나가 적용될 때 비밀이 푸시되는 것을 차단하지 않습니다:

비밀 푸시 보호는 다음과 같은 경우 커밋의 파일을 검사하지 않습니다:

  • 파일이 이진 파일일 때.
  • 파일 크기가 1 MiB보다 클 때.
  • 파일에 대한 diff 패치가 1 MiB보다 클 때 (diff scanning 사용 시).
  • 파일이 내용의 변경 없이 이름이 변경되거나 삭제되었거나 이동되었을 때.
  • 파일의 내용이 소스 코드의 다른 파일 내용과 동일할 때.
  • 파일이 저장소를 생성하는 최초 푸시에 포함되었을 때.

Diff 스캐닝

  • GitLab 17.5에서 소개됨 spp_scan_diffs라는 프로젝트 수준 플래그와 함께.

비밀 푸시 보호는 기본적으로 수정된 파일의 모든 내용을 검사합니다.

이것은 비밀을 포함하는 파일이 스캔될 때 푸시가 예기치 않게 차단되는 원인이 될 수 있습니다.

프로젝트에 대해 spp_scan_diffs 기능 플래그를 활성화하면, 비밀 푸시 보호가 새로 커밋된 변경 사항(또는 차이점)만 스캔하고 나머지는 스캔하지 않도록 수정됩니다.

spp_scan_diffs가 활성화되면 비밀 푸시 보호는 HTTP/SSH를 통한 CLI 기반 푸시에 대한 차이를 검사합니다.

웹 IDE를 통해 커밋된 변경 사항은 기술적 한계로 인해 전체 파일이 스캔되는 결과를 초래합니다. 문제 491282는 웹 IDE 변경 사항에 대해 차이점만 스캔되도록 제한 사항을 설명합니다.

차단된 푸시 해결

비밀 푸시 보호가 푸시를 차단할 때, 다음 방법 중 하나를 선택할 수 있습니다:

비밀 제거

차단된 비밀을 제거하여 커밋을 GitLab에 푸시할 수 있습니다. 비밀 제거 방법은 최근에 커밋된 방법에 따라 다릅니다. 아래 지침은 Git CLI 클라이언트를 사용하지만, 다른 Git 클라이언트를 사용해도 같은 결과를 얻을 수 있습니다.

차단된 비밀이 브랜치에서 가장 최근의 커밋으로 추가된 경우:

  1. 파일에서 비밀을 제거합니다.

  2. git add <file-name>로 변경 사항을 스테이지합니다.

  3. git commit --amend로 변경된 파일을 포함하도록 가장 최근의 커밋을 수정합니다.

  4. git push로 변경 사항을 푸시합니다.

차단된 비밀이 Git 기록에서 이전에 나타나는 경우:

  1. 선택 사항. 커밋에서 비밀을 제거하는 짧은 데모를 시청합니다.

  2. 푸시 오류 메시지에서 커밋 SHA를 식별합니다. 여러 개가 있는 경우, git log를 사용하여 가장 이른 것을 찾습니다.

  3. git switch --create copy-branch를 사용하여 작업할 복사 브랜치를 만듭니다. 이렇게 하면 재배치 중 문제가 발생할 경우 원래 브랜치로 재설정할 수 있습니다.

  4. git rebase -i <commit-sha>~1를 사용하여 인터랙티브 재배치를 시작합니다.

  5. 편집기를 열고 pick 명령을 edit으로 변경하여 수정할 커밋에 표시를 합니다.

  6. 파일에서 비밀을 제거합니다.

  7. git add <file-name>로 변경 사항을 스테이지합니다.

  8. git commit --amend로 변경된 파일을 커밋합니다.

  9. 모든 비밀이 제거될 때까지 git rebase --continue로 재배치를 계속합니다.

  10. 복사 브랜치에서 원래 원격 브랜치로 git push --force --set-upstream origin copy-branch:<original-branch>로 변경 사항을 푸시합니다.

  11. 변경 사항에 만족하면 다음 선택적 정리 단계를 고려합니다.

    1. 선택 사항. git branch --delete --force <original-branch>로 원래 브랜치를 삭제합니다.
    2. 선택 사항. git branch --move copy-branch <original-branch>로 복사 브랜치의 이름을 바꿔 원래 브랜치를 대체합니다.

비밀 푸시 보호 건너뛰기

경우에 따라 비밀 푸시 보호를 건너뛰어야 할 필요가 있을 수 있습니다. 예를 들어, 개발자가 테스트를 위해 자리 표시자 비밀을 커밋해야 하거나 사용자가 Git 작업 타임아웃으로 인해 비밀 푸시 보호를 건너뛰고 싶어할 수 있습니다.

비밀 푸시 보호가 건너뛰어질 때 감사 이벤트가 기록됩니다. 감사 이벤트 세부정보에는 다음이 포함됩니다:

  • 사용된 건너뛰기 방법.
  • GitLab 계정 이름.
  • 비밀 푸시 보호가 건너뛰어진 날짜 및 시간.
  • 비밀이 푸시된 프로젝트의 이름.

파이프라인 비밀 감지가 활성화된 경우, 모든 커밋의 내용은 저장소에 푸시된 후 스캔됩니다.

푸시에서 모든 커밋에 대해 비밀 푸시 보호를 건너뛰려면 다음 중 하나를 선택하십시오:

Git CLI 클라이언트를 사용할 때 건너뛰기

Git CLI 클라이언트를 사용할 때 비밀 푸시 보호를 건너뛰려면:

  • 푸시 옵션을 사용하세요.

    예를 들어, 여러 커밋이 존재하며, 그 중 하나가 비밀 정보를 포함하고 있어 푸시가 차단된 경우가 있습니다. 비밀 푸시 보호를 건너뛰려면 Git 명령어에 푸시 옵션을 추가합니다.

    git push -o secret_push_protection.skip_all

모든 Git 클라이언트를 사용할 때 건너뛰기

모든 Git 클라이언트를 사용할 때 비밀 푸시 보호를 건너뛰려면:

  • 기존 줄이나 새 줄 중 하나에 [skip secret push protection]을 커밋 메시지 중 하나에 추가한 후 커밋을 푸시하세요.

    예를 들어, GitLab Web IDE를 사용하고 있으며 여러 커밋이 존재하지만 그 중 하나가 비밀 정보를 포함하고 있어 푸시가 차단된 경우가 있습니다. 비밀 푸시 보호를 건너뛰려면 최신 커밋 메시지를 편집하고 [skip secret push protection]을 추가한 후 커밋을 푸시합니다.

문제 해결

비밀 푸시 보호를 사용할 때 다음과 같은 상황에 직면할 수 있습니다.

푸시가 예상치 않게 차단됨

비밀 푸시 보호는 수정된 파일의 모든 내용을 스캔합니다. 수정된 파일에 비밀 정보가 포함된 경우, 차이가 없더라도 푸시가 예상치 않게 차단될 수 있습니다.

새로 커밋된 변경 사항만 스캔되도록 spp_scan_diffs 기능 플래그를 활성화하세요. 비밀 정보를 포함하고 있는 파일에 WebIDE 변경 사항을 푸시하려면 비밀 푸시 보호를 건너뛰어야 합니다.

파일이 스캔되지 않음

일부 파일은 스캔에서 제외됩니다. 제외 목록은 coverage를 참조하세요.