diff options
Diffstat (limited to 'doc/development/gemfile.md')
| -rw-r--r-- | doc/development/gemfile.md | 51 |
1 files changed, 49 insertions, 2 deletions
diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index 87304a761ea..7d3531afb49 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -1,20 +1,67 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gemfile guidelines -When adding a new entry to `Gemfile` or upgrading an existing dependency pay +When adding a new entry to `Gemfile`, or upgrading an existing dependency pay attention to the following rules. +## Bundler checksum verification + +In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98508), gem +checksums are checked before installation. This verification is still +experimental so it is only active for CI. + +If the downloaded gem's checksum does not match the checksum record in +`Gemfile.checksum`, you will see an error saying that Bundler cannot continue +installing a gem because there is a potential security issue. + +You will see this error as well if you updated, or added a new gem without +updating `Gemfile.checksum`. To fix this error, +[update the Gemfile.checksum](#updating-the-checksum-file). + +You can opt-in to this verification locally by setting the +`BUNDLER_CHECKSUM_VERIFICATION_OPT_IN` environment variable: + +```shell +export BUNDLER_CHECKSUM_VERIFICATION_OPT_IN=1 +bundle install +``` + +### Updating the checksum file + +This needs to be done for any new, or updated gems. + +1. When updating `Gemfile.lock`, make sure to also update `Gemfile.checksum` with: + + ```shell + bundle exec bundler-checksum init + ``` + +1. Check and commit the changes for `Gemfile.checksum`. + ## No gems fetched from Git repositories We do not allow gems that are fetched from Git repositories. All gems have to be available in the RubyGems index. We want to minimize external build dependencies and build times. +## Review the new dependency for quality + +We should not add 3rd-party dependencies to GitLab that would not pass our own quality standards. +This means that new dependencies should, at a minimum, meet the following criteria: + +- They have an active developer community. At the minimum a maintainer should still be active + to merge change requests in case of emergencies. +- There are no issues open that we know may impact the availablity or performance of GitLab. +- The project is tested using some form of test automation. The test suite must be passing + using the Ruby version currently used by GitLab. +- If the project uses a C extension, consider requesting an additional review from a C or MRI + domain expert. C extensions can greatly impact GitLab stability and performance. + ## Request an Appsec review When adding a new gem to our `Gemfile` or even changing versions in |