2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
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
2021-01-29 00:20:46 +05:30
---
2017-08-17 22:00:37 +05:30
# `Gemfile` guidelines
When adding a new entry to `Gemfile` or upgrading an existing dependency pay
attention to the following rules.
2019-12-04 20:38:33 +05:30
## No gems fetched from Git repositories
2017-08-17 22:00:37 +05:30
2019-12-04 20:38:33 +05:30
We do not allow gems that are fetched from Git repositories. All gems have
2017-08-17 22:00:37 +05:30
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.
2021-03-11 19:13:27 +05:30
## 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`
2021-04-17 20:07:23 +05:30
## 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.
