From 173293fa46e824d3ccf471b7be21389e52b259e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Rodr=C3=ADguez?= Date: Mon, 16 Dec 2024 19:09:13 +0100 Subject: [PATCH] Bundler 2.6 blog post, docs index, and what's new page --- .../2024-12-19-bundler-v2-6.html.markdown | 143 ++++++++++++++++++ source/v2.6/docs.html.haml | 36 +++++ source/v2.6/whats_new.html.md | 21 +++ 3 files changed, 200 insertions(+) create mode 100644 source/blog/2024-12-19-bundler-v2-6.html.markdown create mode 100644 source/v2.6/docs.html.haml create mode 100644 source/v2.6/whats_new.html.md diff --git a/source/blog/2024-12-19-bundler-v2-6.html.markdown b/source/blog/2024-12-19-bundler-v2-6.html.markdown new file mode 100644 index 0000000000..4505d6bdef --- /dev/null +++ b/source/blog/2024-12-19-bundler-v2-6.html.markdown @@ -0,0 +1,143 @@ +--- +title: "Bundler v2.6: lockfile checksums are finally there" +date: 2024-12-19 17:01 UTC +tags: checksums, lockfile +author: David Rodríguez +author_url: https://github.com/deivid-rodriguez +category: release +--- + +We're happy to announce Bundler 2.6, featuring gem checksum verification, right +in the `Gemfile.lock` file. + +This feature has actually been implemented for more than a year. However, it was +merged very close to the Bundler 2.5 release and we did not yet have a good plan for +enabling the feature in a graceful manner, so we've kept it hidden until now. + +Bundler 2.6 finally officially allows to opt-in into this beta feature. + +## What's this feature for? + +A lockfile is an easy way to ensure all environments will use a consistent +version of every dependency. However, Bundler lockfiles did not protect from +potential tampering of the sources of that specific version. This is what the +this feature does. When enabled, Bundler will keep track of the checksum of +every version in the lockfile, in the lockfile itself. Then, before installing +that lockfile on any machine, it will verify that the checksum of the `.gem` +file it's about to install matches the checksum previously recorded in the +lockfile. If they don't match, Bundler will refuse to install that package and +consider it compromised. + +### How to enable lockfile checksums? + +Bundler 2.6 provides two ways of enabling checksums. + +* For a single lockfile, you can run `bundle lock --add-checkums`. This will add + a new `CHECKSUMS` section to the lockfile that Bundler will keep up to date. + +* To configure Bundler to always include checksums in new lockfiles, run `bundle + config lockfile_checksums true`. + +### How does it work, once the feature is enabled? + +Hopefully nothing will ever change for you after enabling the feature. However, +if `bundle install` ever downloads a package (or tries to install it from cache) +the checksum of which does not match what's recorded in the lockfile for that package, +Bundler will print an error like the following and abort installation: + +~~~ +$ bundle install +Fetching gem metadata from https://rubygems.org/........ +Bundler found mismatched checksums. This is a potential security risk. + rake (13.2.1) sha256=46cb38dae65d7d74b6020a4ac9d48afed8eb8149c040eccf0523bec91907059d + from the lockfile CHECKSUMS at Gemfile.lock:1241:17 + and the API at https://rubygems.org/ + rake (13.2.1) sha256=17e8b7c1b247f3349d4a7160c3f587b6c7fd67cf7be3b3710e118b8416f94ddb + from the gem at /my/repo/vendor/cache/rake-13.2.1.gem + +If you trust the lockfile CHECKSUMS at Gemfile.lock:1241:17, to resolve this issue you can: + 1. remove the gem at /my/repo/vendor/cache/rake-13.2.1.gem + 2. run `bundle install` + +To ignore checksum security warnings, disable checksum validation with + `bundle config set --local disable_checksum_validation true` +~~~ + +## Compatibility + +Bundler will keep the `CHECKSUMS` section in the lockfile up to date if it's +already there, and verify that `.gem` packages checksums match what's recorded +in the lockfile before installing. + +On the other hand, Bundler will work like before if it doesn't find a +`CHECKSUMS` section in the lockfile. + +All lockfiles including a `CHECKUMS` section should have Bundler >= 2.6 in the +`BUNDLED WITH` section. Since Bundler internally has a mechanism to make sure it +switches to the version of itself included in the `BUNDLED WITH` lockfile +section, a lockfile with a `CHECKSUMS` section should always be run by +Bundler >= 2.6. + +Some platforms, like Heroku or Dependabot, don't respect this auto-switching +mechanism. However, these platforms are already using Bundler >= 2.5 and +since this feature is luckily already present (but hidden) since Bundler 2.5, +they should deal just fine with new lockfiles including the new section. + +## Should I take any other steps before enabling this feature? + +If your lockfile only includes `ruby` in the `PLATFORMS` section, that means +that Bundler is most likely not storing platform-specific variants of your gems +in the `Gemfile.lock` file. For example, your lockfile may include only +`nokogiri-1.18.0`, while Bundler will actually install the most appropriate +1.18.0 variant for your platform, say `nokogiri-1.18.0-x86_64-linux`. However, +that makes the lockfile checksums feature not work fine for `nokigiri` because +Bundler will only check if the generic variant (what's in the lockfile) is +changed, but not the variant that's actually installed. + +Because of this, Bundler 2.6 will print a warning when it ends up installing a +different variant than the one included in the lockfile, and tell you to +"normalize" the lockfile and add platform specific variants through `bundle lock +--normalize-platforms`. + +## Other notable changes in Bundler 2.6 + +This is a non-exhaustive list of other notable improvements in Bundler 2.6: + +* **Better support for switching between different versions of Ruby.** + +Sometimes when switching between different Ruby versions, even if the resolution +recorded in the Gemfile.lock is stable, the most optimal platform-specific +version for a gem may change. For example, `nokogiri-1.18.0.rc1-x86_64-darwin` +does not support Ruby 3.5, but `nokogiri-1.18.0.rc1` does. Bundler 2.6 should be +able to keep a consistent lockfile with all platform-specific variants, and use +the one that works best for each Ruby version. + +* **Better handling of git dependencies in application caches.** + +Bundler can keep `.gem` packages for your dependencies in `vendor/cache` so +that, for example, they can be installed offline on a different machine. This +did not work fine for git gems, though. Bundler 2.6 should now allow properly +caching git gems in `vendor/cache`. You can enable this with `bundle config +cache_all true`. + +* **More careful redaction of gem server credentials in logs and `bundle config` output.** + +Bundler already did this but we found a few cases where it was not properly +redacting sensitive info and fixed those. + +* **Better `bundle exec` behaviour on Windows.** + +We have introduced several improvements so that `bundle exec` works the usual +way, also on Windows. + +* **Better documentation of commands and CLI flags.** + +We have introduced changes to make sure that this site, and the `bundle` CLI, +properly documents all commands and CLI flags, and made sure it will stay like +that going forward. + +And like always, many other bug fixes and improvements were implemented. Check +[the full Bundler 2.6 changelog](https://github.com/rubygems/rubygems/releases/tag/bundler-v2.6.0) for +details. + +Happy bundling! diff --git a/source/v2.6/docs.html.haml b/source/v2.6/docs.html.haml new file mode 100644 index 0000000000..a38d6c5bb1 --- /dev/null +++ b/source/v2.6/docs.html.haml @@ -0,0 +1,36 @@ +- primary_commands = %w(bundle-install.1 bundle-update.1 bundle-cache.1 bundle-exec.1 bundle-config.1 bundle-help.1) + +.bg-light-blue.header + = image_tag '/images/docs_header_transparent_bg.png', + srcset: '/images/docs_header_transparent_bg.png 1x, /images/docs_header_transparent_bg@2x.png 2x, /images/docs_header_transparent_bg@3x.png 3x', + class: 'img-fluid header-padding', + style: 'max-width: 400px;' + +.container + .row.docs.my-5 + .col-md-6.col-12 + %h3 + %b Guides + %p + Step-by-step tutorials that include useful explanations and detailed instructions to help you get up and running. + %ul.ul-padding + - guides.each do |guide| + %li= link_to_guide guide + %li= link_to "Contributing to Bundler", "/doc/readme.html" + + .col-md-5.offset-md-1.col-12 + %h3 + %b Reference Guides + %p + In-depth articles with information on each primary command and utility, and how to use them. + %h4 + %b Primary Commands + %ul.ul-padding + - primary_commands.select{ |page| path_exist?(page) }.each do |page| + %li= link_to_documentation(page) + + %h4 + %b Utilities + %ul.ul-padding + - other_commands(primary_commands).each do |page| + %li= link_to_documentation(page) diff --git a/source/v2.6/whats_new.html.md b/source/v2.6/whats_new.html.md new file mode 100644 index 0000000000..041d3ba757 --- /dev/null +++ b/source/v2.6/whats_new.html.md @@ -0,0 +1,21 @@ +# What's New in v2.6 + +The [Bundler 2.6 announcement](/blog/2024/12/19/bundler-v2-6.html) +includes context and a more detailed explanation of the changes in this version. +This is a summary of the biggest changes. As always, a detailed list of every change is provided in +[the changelog](https://github.com/rubygems/rubygems/blob/3.6/bundler/CHANGELOG.md). + +## Lockfile checksums + +Bundler 2.6 can now record the checksum of every gem in the lockfile, to make +sure no malicious changes are ever introduced to a locked gem. + +## Other notable changes + +* Better support for switching between different versions of Ruby. +* Better handling of git dependencies in application caches. +* More careful redaction of gem server credentials in logs and `bundle config` output. +* Better `bundle exec` behaviour on Windows. +* Better documentation of commands and CLI flags. + +Full 2.6 changelog