Gemfile 개발 가이드라인

새로운 항목을 Gemfile에 추가하거나 기존 종속성을 업그레이드할 때 다음 규칙에 주의하세요.

Bundler 체크섬 확인

GitLab 15.5 및 이후에서, 젬 체크섬은 설치 전에 확인됩니다. 이 확인은 아직 실험적이므로 CI에서만 활성화됩니다.

다운로드한 젬의 체크섬이 Gemfile.checksum의 기록과 일치하지 않으면, 잠재적 보안 문제가 있기 때문에 Bundler가 젬을 계속 설치할 수 없다는 오류가 표시됩니다.

또한, Gemfile.checksum을 업데이트하지 않고 새로운 젬을 추가하거나 업데이트한 경우에도 이 오류가 표시됩니다. 이 오류를 해결하려면 Gemfile.checksum를 업데이트하세요.

로컬에서 이 확인을 선택하려면 BUNDLER_CHECKSUM_VERIFICATION_OPT_IN 환경 변수를 설정하세요: 

export BUNDLER_CHECKSUM_VERIFICATION_OPT_IN=1
bundle install

false로 설정하여 해제할 수도 있습니다: 

export BUNDLER_CHECKSUM_VERIFICATION_OPT_IN=false
bundle install

체크섬 파일 업데이트

이 작업은 새로운 지뢰 업데이트할 때나 업데이트된 지뢰에 대해 수행되어야 합니다.

  1. Gemfile.lock를 업데이트할 때, 다음과 같이 Gemfile.checksum도 업데이트하세요: 

    bundle exec bundler-checksum init

  2. Gemfile.checksum의 변경 사항을 확인하고 커밋하세요.

Git 저장소에서 가져온 지뢰가 없음

우리는 Git 저장소에서 가져온 지뢰를 허용하지 않습니다. 모든 지뢰는 RubyGems 인덱스에서 사용 가능해야 합니다. 외부 빌드 종속성과 빌드 시간을 최소화하고자 합니다. 이는 RuboCop 규칙 Cop/GemFetcher에 의해 강제됩니다.

새로운 종속성의 품질 검토

GitLab에 우리의 품질 기준을 통과하지 못할 3rd-party 종속성을 추가해서는 안 됩니다. 이는 새로운 종속성이 최소한 다음 기준을 충족해야 함을 의미합니다:

  • 활성 개발자 커뮤니티가 존재해야 합니다. 최소한 유지자는 여전히 비상 시 변경 요청을 병합하기 위해 활동적이어야 합니다.
  • GitLab의 가용성 또는 성능에 영향을 미칠 수 있는 알려진 문제가 없어야 합니다.
  • 프로젝트가 어떤 형태의 자동 테스트를 사용하여 테스트되었어야 합니다. 해당 테스트 스위트는 현재 GitLab에서 사용 중인 Ruby 버전을 사용하여 통과해야 합니다.
  • 모든 지원되는 플랫폼에 대해 CI 빌드가 새로운 종속성을 사용하여 성공해야 합니다. 자세한 내용은 테스트용 패키지 작성을 참조하세요.
  • 프로젝트가 C 확장을 사용하는 경우, C 또는 MRI 도메인 전문가로부터 추가적인 검토를 요청하세요. C 확장은 GitLab의 안정성과 성능에 큰 영향을 줄 수 있습니다.

도메인 전문가 승인이 필요한 지뢰

다음 지뢰에 대한 변경에는 도메인 전문가 검토와 그룹의 백엔드 팀 구성원에 의한 승인이 필요합니다.

이 표에 나열되지 않은 지뢰의 경우에도 도메인 전문가를 찾아 변경 사항을 검토하는 것이 좋지만 필수는 아닙니다.

지뢰 승인 필요자
doorkeeper 관리: 인증 및 권한 부여
doorkeeper-openid_connect 관리: 인증 및 권한 부여

Appsec 검토 요청

우리의 Gemfile에 새로운 지뢰를 추가하거나 Gemfile.lock의 버전을 변경할 때는 보안 검토를 요청하는 것이 좋습니다. 새로운 지뢰는 GitLab에 대한 추가적인 보안 리스크를 추가하며, 이것을 생산 환경으로 배포하기 전에 이 리스크를 평가하는 것이 중요합니다. 기술적으로 단순히 새로운 지뢰를 추가하고 주요 gitlab 프로젝트의 브랜치에 푸시하는 것만으로도 보안 리스크가 있습니다. 따라서 설치하기 전에 이 지뢰가 합법적으로 보이는지 초기에 평가해야 합니다.

검토자는 또한 관련된 커뮤니티 기여 리뷰 권장사항을 인지하고 Gemfile 또는 Gemfile.lock의 변경 사항을 포함하는 커뮤니티 기여의 파이프라인을 실행하기 전에 신중히 검토해야 합니다.

라이센스 준수

라이센스 준수를 보장하기 위한 라이센스 가이드라인을 참조하세요.

GitLab이 생성한 지뢰

우리의 코드베이스 내에서 사용하거나 보다 넓은 커뮤니티에 혜택을 줄 수 있기 때문에 추출하고 싶은 라이브러리를 만들 때가 있습니다. 이러한 코드를 지뢰로 추출하면 우리의 애플리케이션 코드에 숨겨진 종속성이 없음을 확신할 수 있습니다.

Gems 개발 가이드라인에 대해 더 읽어보세요.

Rails 업그레이드

Rails 지뢰와 그 종속성을 업그레이드할 때 다음을 반드시 업데이트해야 합니다:

  • vendored attr_encrypted gemspec의 activerecord_version을 업데이트하세요(https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/gems/attr_encrypted/attr_encrypted.gemspec).
  • qa 디렉터리의 Gemfile을 업데이트하세요(https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/Gemfile).

또한 현재 Rails 버전을 따르는 npm 패키지를 업데이트해야 합니다:

  • @rails/ujs
    • 이를 업데이트한 후 yarn patch-package @rails/ujs를 실행하여 로컬 패치 파일 버전이 일치하도록 합니다.
  • @rails/actioncable

취약점으로 인해 종속성을 업그레이드할 때

취약점으로 인해 종속성을 업그레이드할 때, 취약점이 수정된 지뢰의 최소 버전을 지뢰 파일에 고정해두어야 합니다.

예를 들어, license_finder 지뢰에 thor를 종속성으로 가집니다. thor는 버전 1.1.1에서 취약점이 발견되어 수정되었습니다.

Gemfile에서 thor를 1.1.1로 고정해야 합니다. 직접적인 종속성인 license_finder는 이미 버전이 지정되어 있어야 합니다. 

gem 'license_finder', '~> 6.0'
# 취약점을 수정한 종속성
# _시간이 지날 때 공개될 초기 보안 문제 링크_
gem 'thor', '>= 1.1.1'

여기서 우리는 >= (크거나 같음) 연산자 대신 ~>(비관적 연산자)를 사용하여 license_finder나 thor 1.2에 의존하는 다른 지뢰 버전으로 업그레이드할 수 있도록 합니다.

비슷하게, license_finder에서 6.0.1로 취약점이 수정된 경우, 다음을 추가해야 합니다: 

gem 'license_finder', '~> 6.0', '>= 6.0.1'

이 방법으로 license_finder 이외의 종속성은 6.0.2와 같은 더 최신 버전에 의존할 수 있지만, 취약한 버전인 6.0.0에는 의존할 수 없게 됩니다.

이러한 변경사항은 Gemfile.lock에서 놓칠 수 있는데, 버전을 고정하면 해결해야 하는 충돌이 발생합니다.

간접적인 종속성을 업그레이드하지 않으려면 bundle update --conservative를 사용할 수 있습니다.

종속성 업데이트를 포함한 머지 리퀘스트를 제출할 때는 두 버전 간의 지뢰 차이에 대한 링크를 포함하세요. 이 링크는 rubygems.org에서 찾을 수 있으며, Review Changes를 선택하여 diffend.io에서 버전 간의 비교를 생성할 수 있습니다. 예를 들어, thor 1.0.0 대 1.0.1의 지뢰 차이입니다. 실제로 게시된 코드를 반영하지 않을 수 있기 때문에 GitLab 또는 다른 코드 호스팅 플랫폼에서 생성된 링크보다는 RubyGems에서 직접 생성된 링크를 사용하세요.