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 의존성을 추가하지 말아야 합니다. 이는 최소한 새로운 의존성이 다음 기준을 충족해야 함을 의미합니다:

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

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

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

이 표에 나열되지 않은 젬에 대해서도 도메인 전문가를 찾아 변경 내용을 리뷰하는 것이 좋지만 필수 요건은 아닙니다.

젬 승인이 필요한 사용자
doorkeeper 관리:인증 및 권한
doorkeeper-openid_connect 관리:인증 및 권한

Appsec 리뷰 요청

새로운 젬을 Gemfile에 추가하거나 Gemfile.lock의 버전을 변경할 때는 반드시 보안 리뷰를 요청하십시오. 새로운 젬은 GitLab에 대한 추가적인 보안 리스크를 가지고 있으므로 이를 프로덕션 환경으로 보내기 전에 이 리스크를 평가하는 것이 중요합니다. 기술적으로는, 단순히 새로운 젬을 추가하고 본 gitlab 프로젝트의 브랜치에 푸시하는 것은 보안 리스크입니다. 따라서 설치하기 전에 이 젬이 합법적으로 보인다고 생각하는지를 초기에 평가해야 합니다.

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

라이선스 준수

라이선스 준수를 보장하기 위해 라이선스 지침을 참조하십시오.

GitLab에서 생성한 젬

가끔씩 우리는 다른 애플리케이션에서 사용하려거나 보다 넓은 커뮤니티에 도움이 될 것으로 판단되는 라이브러리를 우리 코드베이스 내에서 생성합니다. 젬으로 코드를 추출하는 것은 또한 해당 젬이 우리의 애플리케이션 코드에 숨겨진 의존성을 포함하지 않는다는 것을 확신할 수 있게 해줍니다.

자세한 내용은 젬 개발 지침을 참조하십시오.

Rails 업그레이드

Rails 젬 및 해당 의존성을 업그레이드할 때 다음도 업데이트해야 합니다.

또한 현재 버전의 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'

여기서 우리는 비관적 연산자인 ~> 대신 >= (이상) 연산자를 사용하여 thor 1.2에 의존하는 license_finder 또는 기타 어떤 젬도 업그레이드할 수 있게 만들어주었습니다.

비슷하게, 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을 사용할 수 있습니다.

취약성으로 인해 의존성을 업그레이드 하는 Merge Request을 제출할 때는 Merge Request 설명에 두 버전 간의 Gem 차이 링크를 포함하십시오. 이 링크는 rubygems.org에서 찾을 수 있으며 Review Changes 를 선택하여 diffend.io에서 버전 간의 비교를 생성할 수 있습니다. 예를 들어, 이것은 thor 1.0.0 vs 1.0.1에 대한 젬 diff입니다. GitLab 또는 다른 코드 호스팅 플랫폼의 링크는 실제로 게시된 코드를 반영하지 않을 수 있으므로 RubyGems에서 직접 생성된 링크를 사용하십시오.