Gemfile 개발 지침

새로운 항목을 Gemfile에 추가하거나 기존 의존성을 업그레이드할 때 다음 규칙에 유의하십시오.

Bundle 체크섬 확인

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이나 업데이트된 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의 안정성과 성능에 큰 영향을 줄 수 있습니다.

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

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

이 표에 나열되지 않은 gem에 대해서는 아직 필수는 아니지만 해당 변경 사항을 검토할 도메인 전문가를 찾는 것이 좋습니다.

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

Appsec 검토 요청

Gemfile에 새로운 gem을 추가하거나 Gemfile.lock에서 버전을 변경할 때는 반드시 보안 검토를 요청하십시오. 새로운 gem은 GitLab에 대한 추가적인 보안 위험을 야기하며, 운영 환경에 배포하기 전에 이 위험을 평가하는 것이 중요합니다. 기술적으로는, 단순히 새로운 gem을 추가하고 주요 gitlab 프로젝트의 브랜치에 푸시하는 것만으로도 보안 위험을 야기할 수 있습니다. 따라서 설치하기 전에 해당 gem이 정당한 것으로 판단하는 것이 중요합니다.

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

라이선스 규정 준수

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

GitLab에서 생성한 gem

가끔 우리는 자체 코드베이스 내에서 라이브러리를 생성하여 이를 추출하고 싶어합니다. 이는 우리 자신의 다른 응용프로그램에서 사용하고 싶어서거나 더 넓은 커뮤니티에 이로운 영향을 줄 것으로 생각하기 때문입니다. 코드를 gem으로 추출하는 것은 또한 해당 gem에 우리의 애플리케이션 코드에 대한 숨겨진 의존성이 없음을 확신할 수 있다는 것을 의미합니다.

Gem 개발 지침에 대해 자세히 읽어보세요.

Rails 업그레이드

Rails gem 및 해당 의존성을 업그레이드할 때 다음 사항도 업데이트해야 합니다:

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

  • @rails/ujs
    • 이를 업데이트한 후 yarn patch-package @rails/ujs를 실행하여 로컬 패치 파일 버전이 일치함을 보장하십시오.
  • @rails/actioncable

취약점으로 인해 의존성 업그레이드

취약점 때문에 의존성을 업그레이드할 때, 우리는 취약점이 수정된 최소한의 gem 버전을 우리의 Gemfile에 고정해두는 것이 좋습니다.

예를 들어, license_finder gem이 thor를 의존성으로 가지고 있는데, thor는 버전 1.1.1까지 취약점이 발견되어 있었습니다.

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

gem 'license_finder', '~> 6.0'
# 취약점을 수정한 의존성인 license_finder
# _시간이 지나면 공개될 초기 보안 이슈에 대한 링크_
gem 'thor', '>= 1.1.1'

여기서 >= (이상) 연산자를 사용하여 license_finder나 다른 gem을 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을 사용할 수 있습니다.

취약점으로 인해 의존성을 업그레이드하는 머지 요청을 제출할 때, m에거봇 설명에 2개의 버전 간의 Gem 차이 링크를 포함해야 합니다. rubygems.org에서 이 링크를 찾아 Review Changes를 선택하여 diffend.io에서 버전 간의 비교를 생성할 수 있습니다. 예를 들어, thor 1.0.0 대 1.0.1에 대한 gem 차이는 여기에서 확인하실 수 있습니다. 이 링크는 실제로 발행된 코드와는 다를 수 있는 GitLab이나 다른 코드 호스팅 플랫폼에서 생성된 링크가 아니므로, 직접적으로 RubyGems에서 생성된 링크를 사용하여야 합니다.