Gemfile 개발 지침

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

Bundler 체크섬 검증

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

다운로드한 gem의 체크섬이 Gemfile.checksum에 기록된 체크섬과 일치하지 않으면 Bundler가 gem 설치를 계속할 수 없다는 오류 메시지가 표시됩니다.

새로운 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 Manage:Authentication and Authorization
doorkeeper-openid_connect Manage:Authentication and Authorization

앱 보안 리뷰 요청

새로운 gem을 Gemfile에 추가하거나, Gemfile.lock에서 버전을 변경할 때는 반드시 보안 리뷰 요청을 권장합니다.

새로운 gem은 GitLab에 추가적인 보안 위험을 더하므로, 이를 프로덕션으로 배포하기 전에 이 위험을 평가하는 것이 중요합니다. 기술적으로 새로운 gem을 추가하고 우리의 주요 gitlab 프로젝트의 브랜치에 푸시하는 것은 CI 내에서 GitLab.com 자격 증명을 사용하게 되므로 보안 위험입니다. 따라서 설치하기 전에 이 gem이 적법한지 조기에 평가해야 합니다.

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

라이센스 준수

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

GitLab에서 생성한 gem

가끔 우리는 다른 애플리케이션에서 사용하기 위해 또는 더 넓은 커뮤니티에 도움이 될 것으로 생각되어 코드베이스 내에서 라이브러리를 생성합니다.

코드를 gem으로 추출하는 것은 gem이 우리의 애플리케이션 코드에 대한 숨겨진 종속성을 포함하지 않도록 보장할 수 있다는 것을 의미합니다.

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

Rails 업그레이드

Rails gem 및 그 종속성을 업그레이드할 때는 다음을 업데이트해야 합니다:

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

  • @rails/ujs
    • 이 패키지를 업데이트한 후 yarn patch-package @rails/ujs를 실행하여 로컬 패치 파일 버전이 일치하는지 확인하세요.
  • @rails/actioncable

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

취약점으로 인해 종속성을 업그레이드할 때는 Gemfile에서 취약점이 수정된 gem의 최소 버전을 고정해야 실수로 다운그레이드되지 않도록 할 수 있습니다.

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

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

gem 'license_finder', '~> 6.0'
# 취약점 수정이 포함된 license_finder의 종속성
# _추후 공개될 초기 보안 이슈에 대한 링크_
gem 'thor', '>= 1.1.1'

여기에서는 ~>(비관적 연산자](https://thoughtbot.com/blog/rubys-pessimistic-operator))가 아닌 >= (이상) 연산자를 사용하여 license_finder 또는 다른 gem을 thor 1.2에 의존하는 버전으로 업그레이드할 수 있습니다.

유사하게, license_finder에 6.0.1에서 수정된 취약점이 있다면, 다음을 추가해야 합니다:

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

이렇게 하면 다른 종속성이 license_finder 대신 thor의 최신 버전인 6.0.2에 여전히 의존할 수 있지만, 취약한 버전인 6.0.0에는 의존할 수 없게 됩니다.

이러한 다운그레이드는 우리는 thor에 의존하는 새로운 종속성을 도입했지만 해당 버전이 취약한 것으로 고정되었을 때 발생할 수 있습니다. 이러한 변경 사항은 Gemfile.lock에서 놓치기 쉽습니다. 버전을 고정하면 해결해야 할 충돌이 발생하게 됩니다.

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

의존성 업데이트가 포함된 병합 요청을 제출할 때는 병합 요청 설명에 두 버전 간의 Gem diff에 대한 링크를 포함해야 합니다. 해당 링크는 rubygems.org에서 찾을 수 있으며, 변경 검토를 선택하여 diffend.io에서 버전 간의 비교를 생성할 수 있습니다. 예를 들어, thor 1.0.0과 1.0.1 간의 gem diff입니다. RubyGems에서 직접 생성된 링크를 사용하십시오. GitLab이나 다른 코드 호스팅 플랫폼의 링크는 실제로 게시된 코드와 일치하지 않을 수 있습니다.