88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
---
|
|
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
|
|
---
|
|
|
|
# `Gemfile` guidelines
|
|
|
|
When adding a new entry to `Gemfile` or upgrading an existing dependency pay
|
|
attention to the following rules.
|
|
|
|
## 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.
|
|
|
|
## License compliance
|
|
|
|
Refer to [licensing guidelines](licensing.md) for ensuring license compliance.
|
|
|
|
## Upgrade Rails
|
|
|
|
When upgrading the Rails gem and its dependencies, you also should update the following:
|
|
|
|
- The [`Gemfile` in the `qa` directory](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/Gemfile).
|
|
- The [`Gemfile` in Gitaly Ruby](https://gitlab.com/gitlab-org/gitaly/-/blob/master/ruby/Gemfile),
|
|
to ensure that we ship only one version of these gems.
|
|
|
|
You should also update npm packages that follow the current version of Rails:
|
|
|
|
- `@rails/ujs`
|
|
- `@rails/actioncable`
|
|
|
|
## Upgrading dependencies because of vulnerabilities
|
|
|
|
When upgrading dependencies because of a vulnerability, we
|
|
should pin the minimal version of the gem in which the vulnerability
|
|
was fixed in our Gemfile to avoid accidentally downgrading.
|
|
|
|
For example, consider that the gem `license_finder` has `thor` as its
|
|
dependency. `thor` was found vulnerable until its version `1.1.1`,
|
|
which includes the vulnerability fix.
|
|
|
|
In the Gemfile, make sure to pin `thor` to `1.1.1`. The direct
|
|
dependency `license_finder` should already have the version specified.
|
|
|
|
```ruby
|
|
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'
|
|
```
|
|
|
|
Here we're using the operator `>=` (greater than or equal to) rather
|
|
than `~>` ([pessimistic
|
|
operator](https://thoughtbot.com/blog/rubys-pessimistic-operator))
|
|
making it possible to upgrade `license_finder` or any other gem to a
|
|
version that depends on `thor 1.2`.
|
|
|
|
Simlarly, if `license_finder` had a vulnerability fixed in 6.0.1, we
|
|
should add:
|
|
|
|
```ruby
|
|
gem 'license_finder', '~> 6.0', '>= 6.0.1'
|
|
```
|
|
|
|
This way, other dependencies rather than `license_finder` can
|
|
still depend on a newer version of `thor`, such as `6.0.2`, but would
|
|
not be able to depend on the vulnerable version `6.0.0`.
|
|
|
|
A downgrade like that could happen if we introduced a new dependency
|
|
that also relied on thor but had its version pinned to a vulnerable
|
|
one. These changes are easy to miss in the `Gemfile.lock`. Pinning the
|
|
version would result in a conflict that would need to be solved.
|
|
|
|
To avoid upgrading indirect dependencies, we can use [`bundle update
|
|
--conservative`](https://bundler.io/man/bundle-update.1.html#OPTIONS).
|
|
|
|
When submitting a merge request including a dependency update,
|
|
include a link to the Gem diff between the 2 versions in the merge request
|
|
description. You can find this link on `rubygems.org` under
|
|
**Review Changes**. When you click it, RubyGems generates a comparison
|
|
between the versions on `diffend.io`. For example, this is the gem
|
|
diff for [`thor` 1.0.0 vs
|
|
1.0.1](https://my.diffend.io/gems/thor/1.0.0/1.0.1). Use the
|
|
links directly generated from RubyGems, since the links from GitLab or other code-hosting
|
|
platforms might not reflect the code that's actually published.
|