Gemfile 개발 지침

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

Bundler 체크섬 확인

GitLab 15.5 이후에서 gem 체크섬이 설치 전에 확인됩니다. 이 확인은 여전히 실험적이므로 CI에서만 활성화되어 있습니다.

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

또한 Gemfile.checksum를 업데이트하지 않고 gem을 업데이트하거나 추가한 경우에도 이 오류가 표시됩니다. 이 오류를 해결하려면, 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

체크섬 파일 업데이트

이것은 새로운 또는 업데이트된 gem에 대해 수행해야 합니다.

  1. Gemfile.lock을 업데이트할 때, 다음과 같이 Gemfile.checksum도 반드시 업데이트하십시오: 

    bundle exec bundler-checksum init

  2. Gemfile.checksum에 대한 변경 사항을 확인하고 커밋합니다.

Git 저장소에서 가져온 gem 없음

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

새로운 종속성의 품질 검토

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

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

도메인 전문가 승인이 필요한 Gems

다음 Gems에 대한 변경사항에는 도메인 전문가 검토와 그룹의 백엔드 팀 멤버의 승인이 필요합니다.

이 표에 나열되지 않은 Gems의 경우에도 도메인 전문가를 찾아 리뷰하는 것이 좋지만 필수는 아닙니다.

Gem 승인이 필요한 사람
doorkeeper Manage:Authentication and Authorization
doorkeeper-openid_connect Manage:Authentication and Authorization

Appsec 리뷰 요청

새로운 gem을 Gemfile에 추가하거나 Gemfile.lock에서 버전을 변경하는 경우, 권장사항으로 보안 리뷰를 요청합니다. 새로운 gems는 GitLab에 대한 추가적인 보안 리스크를 가지며, 이를 생산 환경에 배포하기 전에 이 리스크를 평가하는 것이 중요합니다. 기술적으로는, 단순히 새로운 gem을 추가하고 주요 gitlab 프로젝트의 브랜치에 푸시하는 것만으로도 보안 리스크가 발생하며 GitLab.com 자격 증명을 사용하여 CI에서 실행됩니다. 따라서 이 gem이 합법적으로 보인다고 생각하기 전에 초기에 평가해야 합니다.

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

라이선스 컴플라이언스

라이선싱 준수를 보장하는 라이선싱 가이드라인을 참조하십시오.

GitLab이 생성한 Gems

때로는 우리 코드베이스 내에서 라이브러리를 생성하여 추출하길 원합니다. 이것은 우리가 그들을 다른 애플리케이션에서 사용하고 싶어하기 때문에, 또는 더 넓은 커뮤니티에 이로운 것으로 생각하기 때문입니다. 코드를 gem으로 추출하는 것은 또한 해당 gem이 우리의 애플리케이션 코드에 숨겨진 의존성이 없음을 확신할 수 있게 해줍니다.

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

취약점으로 인한 종속성 업그레이드

취약점으로 인해 종속성을 업그레이드할 때, 우리는 취약점이 수정된 최소 버전의 젬을 우리의 Gemfile에 고정시켜 의도치 않은 다운그레이드를 피해야합니다.

예를 들어, 젬 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와 같이 더 새로운 버전의 thor에 의존할 수 있지만, 취약한 버전인 6.0.0에 대해서는 의존할 수 없습니다.

이와 같은 다운그레이드는 우리가 Gemfile.lock에서 놓치기 쉽습니다. 버전을 고정시키면 해결해야할 충돌이 발생합니다.

간접 종속성 업그레이드를 피하기 위해 bundle update --conservative를 사용할 수 있습니다.

종속성 업데이트를 포함하는 병합 요청을 제출할 때, 병합 요청 설명에 2개 버전의 젬 차이를 나타내는 링크를 포함하세요. 이 링크는 rubygems.org에서 찾을 수 있습니다. Review Changes를 선택하여 diffend.io에서 버전 간의 비교를 생성합니다. 예를 들어, thor 1.0.0 vs 1.0.1의 경우입니다. GitLab 또는 다른 코드 호스팅 플랫폼에서 생성된 링크보다 실제로 게시된 코드를 반영하는 링크를 사용하세요.