InfoGrab DocsInfoGrab Docs

Gemfile 개발 가이드라인

요약

Gemfile에 새 항목을 추가하거나 기존 의존성을 업그레이드할 때 다음 규칙에 주의하세요. GitLab 19.0에서 이제 네이티브 Bundler 체크섬 검증으로 전환되었습니다. 기존 bundler-checksum gem은 이제 더 이상 사용되지 않습니다.

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

Bundler 체크섬 검증#

GitLab 19.0에서 이제 네이티브 Bundler 체크섬 검증으로 전환되었습니다.

기존 bundler-checksum gem은 이제 더 이상 사용되지 않습니다. 다음 항목의 사용을 모두 제거해 주세요:

  • BUNDLER_CHECKSUM_VERIFICATION_OPT_IN

  • bundle exec bundler-checksum init

  • bundle exec bundler-checksum lint

체크섬 파일 업데이트#

bundle install이 이제 자동으로 Gemfile.lock의 CHECKSUMS 섹션을 업데이트합니다.

Gemfile.next.lock 파일 업데이트#

gem이 업데이트될 때마다 Gemfile.next.lock 파일이 일관성을 유지하도록 확인하세요.

  • gem 파일 동기화 Gemfile.checksum을 업데이트한 경우, 다음 명령을 실행하여 gem 파일을 동기화해야 합니다:

    bundle exec rake bundler:gemfile:sync

  • 변경 사항 검토 및 커밋 동기화 후 업데이트 내용을 확인하고 Gemfile.next.checksum과 Gemfile.next.lock의 변경 사항을 커밋합니다.

Git 리포지터리에서 gem 가져오기 금지#

Git 리포지터리에서 가져오는 gem은 허용하지 않습니다. 모든 gem은 RubyGems 인덱스에서 사용 가능해야 합니다. 외부 빌드 의존성과 빌드 시간을 최소화하려고 합니다. 이 규칙은 RuboCop 규칙 Cop/GemFetcher로 강제됩니다.

임포터나 통합에서 HTTP 호출을 하는 gem 금지#

임포터나 통합에서 HTTP 호출을 하는 gem을 추가하지 마세요. 일반적으로 이러한 도메인에서는 다른 gem도 강력히 권장하지 않습니다. 자세한 내용은 다음을 참조하세요:

새 의존성의 품질 검토#

당사의 품질 기준을 충족하지 못하는 3rd-party 의존성을 GitLab에 추가해서는 안 됩니다. 즉, 새로운 의존성은 최소한 다음 기준을 충족해야 합니다:

  • 활발한 개발자 커뮤니티가 있어야 합니다. 최소한 유지 관리자가 여전히 활동 중이어서 긴급 상황 시 변경 요청을 머지할 수 있어야 합니다.

  • 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

Appsec 리뷰 요청#

Gemfile에 새 gem을 추가하거나 Gemfile.lock의 버전을 변경할 때는 보안 리뷰 요청을 강력히 권장합니다. 새 gem은 GitLab에 추가적인 보안 위험을 더하므로, 프로덕션에 배포하기 전에 이 위험을 평가하는 것이 중요합니다. 기술적으로, 새 gem을 추가하고 메인 gitlab 프로젝트의 브랜치에 푸시하는 것만으로도 GitLab.com 자격 증명을 사용하여 CI에서 실행되므로 보안 위험이 있습니다. 따라서 설치하기 전에 이 gem이 합법적으로 보이는지 미리 평가해야 합니다.

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

라이선스 준수#

라이선스 준수를 보장하려면 라이선스 가이드라인을 참조하세요.

GitLab이 만든 gem#

때로는 코드베이스 내에서 라이브러리를 만들어 추출하고 싶은 경우가 있습니다. 이는 다른 애플리케이션에서 직접 사용하거나, 더 넓은 커뮤니티에 도움이 될 것이라고 생각하기 때문입니다. 코드를 gem으로 추출하면 해당 gem이 애플리케이션 코드에 숨겨진 의존성이 없음을 확실히 할 수 있습니다.

Gems 개발 가이드라인에서 자세한 내용을 읽어보세요.

Rails 업그레이드#

  • 새 버전으로 업그레이드하기 전에 모든 Gitlab.next_rails? 체크가 정리되었는지 확인하세요.

  • Gemfile.next의 Rails 버전을 다음 Rails 버전으로 업그레이드하는 머지 리퀘스트를 생성하세요.

    Gemfile에 next? 조건을 추가하여 이를 달성할 수 있습니다:

    if next?
  gem 'rails', '~> 8.0.4', feature_category: :shared
else
  gem 'rails', '~> 7.2.3', feature_category: :shared
end

    gems/activerecord-gitlab/Gemfile, gems/gitlab-backup-cli/Gemfile, gems/gitlab-database-load_balancing/Gemfile도 포함하세요.

  • rails-next 예약된 파이프라인이 통과하는지 확인하세요. 다음 버전으로 Gemfile을 업그레이드하는 드래프트 머지 리퀘스트를 만들어 새 파이프라인을 쉽게 실행하고 수정 사항을 테스트할 수도 있습니다.

    rails-next에 대한 수정은 더 쉬운 리뷰를 위해 별도의 머지 리퀘스트에서 진행할 수 있습니다. 코드베이스는 현재와 다음 Rails 버전 모두에서 작동해야 합니다. 필요한 경우 Gitlab.next_rails? 조건을 사용하세요.

  • Delivery 팀과 테스트 롤아웃을 조율하세요.

  • Gemfile을 다음 Rails 버전을 사용하도록 업그레이드하세요. 2단계에서 나열된 벤더 gem의 Gemfile과 qa 디렉터리의 Gemfile도 포함하세요.

    현재 Rails 버전을 따르는 @rails/actioncable NPM 패키지도 업데이트해야 합니다.

    다음 패치 릴리스로 업그레이드하는 경우, 5단계로 건너뛰어 Gemfile과 NPM 패키지를 직접 업그레이드할 수 있습니다.

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

취약점으로 인해 의존성을 업그레이드할 때는 의도치 않은 다운그레이드를 방지하기 위해 Gemfile에 취약점이 수정된 gem의 최소 버전을 고정해야 합니다.

예를 들어, gem license_finder가 thor를 의존성으로 가지고 있다고 가정합니다. thor는 버전 1.1.1까지 취약한 것으로 밝혀졌으며, 해당 버전에 취약점 수정이 포함되어 있습니다.

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

gem 'license_finder', '~> 6.0'
# Dependency of license_finder with fix for vulnerability
# _link to initial security issue that will become public in time_
gem 'thor', '>= 1.1.1'

여기서는 ~> (비관적 연산자) 대신 >= (크거나 같음) 연산자를 사용하여 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 차이 링크를 포함하세요. 이 링크는 rubygems.org에서 찾을 수 있으며, Review Changes를 선택하면 diffend.io에서 버전 간 비교가 생성됩니다. 예를 들어, 이것은 thor 1.0.0 vs 1.0.1의 gem 차이입니다. 실제로 게시된 코드를 반영하지 않을 수 있는 GitLab이나 다른 코드 호스팅 플랫폼의 링크 대신 RubyGems에서 직접 생성된 링크를 사용하세요.

Gemfile 개발 가이드라인

GitLab v19.1
원문 보기
요약

Gemfile에 새 항목을 추가하거나 기존 의존성을 업그레이드할 때 다음 규칙에 주의하세요. GitLab 19.0에서 이제 네이티브 Bundler 체크섬 검증으로 전환되었습니다. 기존 bundler-checksum gem은 이제 더 이상 사용되지 않습니다.

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

Bundler 체크섬 검증#

GitLab 19.0에서 이제 네이티브 Bundler 체크섬 검증으로 전환되었습니다.

기존 bundler-checksum gem은 이제 더 이상 사용되지 않습니다. 다음 항목의 사용을 모두 제거해 주세요:

  • BUNDLER_CHECKSUM_VERIFICATION_OPT_IN

  • bundle exec bundler-checksum init

  • bundle exec bundler-checksum lint

체크섬 파일 업데이트#

bundle install이 이제 자동으로 Gemfile.lock의 CHECKSUMS 섹션을 업데이트합니다.

Gemfile.next.lock 파일 업데이트#

gem이 업데이트될 때마다 Gemfile.next.lock 파일이 일관성을 유지하도록 확인하세요.

  • gem 파일 동기화 Gemfile.checksum을 업데이트한 경우, 다음 명령을 실행하여 gem 파일을 동기화해야 합니다:

    bundle exec rake bundler:gemfile:sync

  • 변경 사항 검토 및 커밋 동기화 후 업데이트 내용을 확인하고 Gemfile.next.checksum과 Gemfile.next.lock의 변경 사항을 커밋합니다.

Git 리포지터리에서 gem 가져오기 금지#

Git 리포지터리에서 가져오는 gem은 허용하지 않습니다. 모든 gem은 RubyGems 인덱스에서 사용 가능해야 합니다. 외부 빌드 의존성과 빌드 시간을 최소화하려고 합니다. 이 규칙은 RuboCop 규칙 Cop/GemFetcher로 강제됩니다.

임포터나 통합에서 HTTP 호출을 하는 gem 금지#

임포터나 통합에서 HTTP 호출을 하는 gem을 추가하지 마세요. 일반적으로 이러한 도메인에서는 다른 gem도 강력히 권장하지 않습니다. 자세한 내용은 다음을 참조하세요:

새 의존성의 품질 검토#

당사의 품질 기준을 충족하지 못하는 3rd-party 의존성을 GitLab에 추가해서는 안 됩니다. 즉, 새로운 의존성은 최소한 다음 기준을 충족해야 합니다:

  • 활발한 개발자 커뮤니티가 있어야 합니다. 최소한 유지 관리자가 여전히 활동 중이어서 긴급 상황 시 변경 요청을 머지할 수 있어야 합니다.

  • 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

Appsec 리뷰 요청#

Gemfile에 새 gem을 추가하거나 Gemfile.lock의 버전을 변경할 때는 보안 리뷰 요청을 강력히 권장합니다. 새 gem은 GitLab에 추가적인 보안 위험을 더하므로, 프로덕션에 배포하기 전에 이 위험을 평가하는 것이 중요합니다. 기술적으로, 새 gem을 추가하고 메인 gitlab 프로젝트의 브랜치에 푸시하는 것만으로도 GitLab.com 자격 증명을 사용하여 CI에서 실행되므로 보안 위험이 있습니다. 따라서 설치하기 전에 이 gem이 합법적으로 보이는지 미리 평가해야 합니다.

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

라이선스 준수#

라이선스 준수를 보장하려면 라이선스 가이드라인을 참조하세요.

GitLab이 만든 gem#

때로는 코드베이스 내에서 라이브러리를 만들어 추출하고 싶은 경우가 있습니다. 이는 다른 애플리케이션에서 직접 사용하거나, 더 넓은 커뮤니티에 도움이 될 것이라고 생각하기 때문입니다. 코드를 gem으로 추출하면 해당 gem이 애플리케이션 코드에 숨겨진 의존성이 없음을 확실히 할 수 있습니다.

Gems 개발 가이드라인에서 자세한 내용을 읽어보세요.

Rails 업그레이드#

  • 새 버전으로 업그레이드하기 전에 모든 Gitlab.next_rails? 체크가 정리되었는지 확인하세요.

  • Gemfile.next의 Rails 버전을 다음 Rails 버전으로 업그레이드하는 머지 리퀘스트를 생성하세요.

    Gemfile에 next? 조건을 추가하여 이를 달성할 수 있습니다:

    if next?
  gem 'rails', '~> 8.0.4', feature_category: :shared
else
  gem 'rails', '~> 7.2.3', feature_category: :shared
end

    gems/activerecord-gitlab/Gemfile, gems/gitlab-backup-cli/Gemfile, gems/gitlab-database-load_balancing/Gemfile도 포함하세요.

  • rails-next 예약된 파이프라인이 통과하는지 확인하세요. 다음 버전으로 Gemfile을 업그레이드하는 드래프트 머지 리퀘스트를 만들어 새 파이프라인을 쉽게 실행하고 수정 사항을 테스트할 수도 있습니다.

    rails-next에 대한 수정은 더 쉬운 리뷰를 위해 별도의 머지 리퀘스트에서 진행할 수 있습니다. 코드베이스는 현재와 다음 Rails 버전 모두에서 작동해야 합니다. 필요한 경우 Gitlab.next_rails? 조건을 사용하세요.

  • Delivery 팀과 테스트 롤아웃을 조율하세요.

  • Gemfile을 다음 Rails 버전을 사용하도록 업그레이드하세요. 2단계에서 나열된 벤더 gem의 Gemfile과 qa 디렉터리의 Gemfile도 포함하세요.

    현재 Rails 버전을 따르는 @rails/actioncable NPM 패키지도 업데이트해야 합니다.

    다음 패치 릴리스로 업그레이드하는 경우, 5단계로 건너뛰어 Gemfile과 NPM 패키지를 직접 업그레이드할 수 있습니다.

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

취약점으로 인해 의존성을 업그레이드할 때는 의도치 않은 다운그레이드를 방지하기 위해 Gemfile에 취약점이 수정된 gem의 최소 버전을 고정해야 합니다.

예를 들어, gem license_finder가 thor를 의존성으로 가지고 있다고 가정합니다. thor는 버전 1.1.1까지 취약한 것으로 밝혀졌으며, 해당 버전에 취약점 수정이 포함되어 있습니다.

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

gem 'license_finder', '~> 6.0'
# Dependency of license_finder with fix for vulnerability
# _link to initial security issue that will become public in time_
gem 'thor', '>= 1.1.1'

여기서는 ~> (비관적 연산자) 대신 >= (크거나 같음) 연산자를 사용하여 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 차이 링크를 포함하세요. 이 링크는 rubygems.org에서 찾을 수 있으며, Review Changes를 선택하면 diffend.io에서 버전 간 비교가 생성됩니다. 예를 들어, 이것은 thor 1.0.0 vs 1.0.1의 gem 차이입니다. 실제로 게시된 코드를 반영하지 않을 수 있는 GitLab이나 다른 코드 호스팅 플랫폼의 링크 대신 RubyGems에서 직접 생성된 링크를 사용하세요.