gdk update fails if gitlab-docs has gems that need to be installed
Overview
It looks like gitlab-docs has been using Ruby 3.2.4 since May 2024 (gitlab-docs!4809 (merged)), while the rest of the GDK is using Ruby 3.2.3.
@rdickenson first experienced this problem after doing a gdk update
. If gitlab-docs
is enabled and auto-updated, gdk update
will fail because while the bundle check
uses the right Ruby version (3.2.4), the actual make compile
appears to use the GDK version (3.2.3):
▶ make gitlab-docs-update
--------------------------------------------------------------------------------
Updating gitlab-org/gitlab-docs
--------------------------------------------------------------------------------
:white_check_mark:️ Successfully fetched and checked out 'main' for 'gitlab-development-kit/'
:white_check_mark:️ Successfully pulled (--ff-only) for 'gitlab-development-kit/'
--------------------------------------------------------------------------------
Installing asdf tools from /Users/russell/work/gitlab-development-kit/gitlab-docs/.tool-versions
--------------------------------------------------------------------------------
INFO: Installing asdf dependencies...
minify 2.20.19 is already installed
nodejs 20.14.0 is already installed
ruby 3.2.4 is already installed
shellcheck 0.10.0 is already installed
--------------------------------------------------------------------------------
Installing gitlab-org/gitlab-docs Ruby gems
--------------------------------------------------------------------------------
Bundle check passed.
➤ YN0088: A new stable version of Yarn is available: 4.3.1!
➤ YN0088: Upgrade now by running yarn set version 4.3.1
➤ YN0000: · Yarn 4.1.1
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed in 0s 349ms
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed
➤ YN0000: · Done in 0s 643ms
INFO: Checking for GitLab documentation content...
INFO: GitLab documentation exists!
INFO: Checking for GitLab Runner documentation content...
WARNING: GitLab Runner documentation is missing. If unexpected, see <https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md#troubleshooting> for more information.
INFO: Checking for Omnibus GitLab documentation content...
WARNING: Omnibus GitLab documentation is missing. If unexpected, see <https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md#troubleshooting> for more information.
INFO: Checking for GitLab Charts documentation content...
WARNING: GitLab Charts documentation is missing. If unexpected, see <https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md#troubleshooting> for more information.
INFO: Checking for GitLab Operator documentation content...
WARNING: GitLab Operator documentation is missing. If unexpected, see <https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md#troubleshooting> for more information.
INFO: No search backend specified. Compiling GitLab documentation site with Google Programmable Search...
INFO: GOOGLE_SEARCH_KEY environment variable not detected! For more information, see https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/search.md.
Could not find json_schemer-2.3.0, nokogiri-1.16.5, rspec-mocks-3.13.1, rspec-parameterized-core-1.0.1, rexml-3.2.8, simpleidn-0.2.3, concurrent-ruby-1.3.1, rb-inotify-0.11.1, asciidoctor-2.0.23, mini_portile2-2.8.6, parser-3.3.2.0, proc_to_ast-0.2.0, activesupport-7.1.3.3, rack-3.0.11, minitest-5.23.1 in locally installed gems
Run `bundle install` to install missing gems.
ERROR: Compilation failed! Try running 'make setup'.
make[2]: *** [compile] Error 1
make[1]: *** [gitlab-docs-build] Error 2
make: *** [gitlab-docs-update-timed] Error 2
I'm not sure why this started happening; I noticed my gitlab-docs had not auto-updated in a while. I had to manually git pull
it to see the same issue. Perhaps after a number of Ruby dependencies were recently updated (gitlab-docs!4877 (merged)), this became a problem.
The current workaround is to install the gems for both Ruby 3.2.3 and 3.2.4 inside the gitlab-docs
directory:
ASDF_RUBY_VERSION=3.2.3 bundle install
ASDF_RUBY_VERSION=3.2.4 bundle install
Reproduction steps
To reproduce the issue:
- Enable gitlab-docs in
gdk.yml
:
gitlab_docs:
auto_update: true
enabled: true
- Ensure that at least one of the gems needed by
gitlab-docs
is not available for Ruby 3.2.3. For example:
ASDF_RUBY_VERSION=3.2.3 gem uninstall json_schemer -v 2.3.0
- Run
make gitlab-docs-update
(this is faster than runninggdk update
)
Investigation
The problem appears to happen because:
-
support/update-path
sets thePATH
to include theRUBY_VERSION
from thegitlab
dir: https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/fcaa82b746ec0ed57013be09f850509bc8637bd7/support/makefiles/Makefile.gitlab.mk#L8, https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/fcaa82b746ec0ed57013be09f850509bc8637bd7/support/update-path#L13 - As a result, even if we attempt to set
ASDF_RUBY_VERSION
orASDF_DEFAULT_TOOL_VERSIONS_FILENAME
, this has no effect.
I wonder if we should avoid setting PATH
this way as it makes it difficult to have multiple Ruby versions in the projects. Instead, perhaps we should probably set environment variables locally for all the calls within each respective Makefile
so that we don't pollute the global PATH
.
Impacted categories
The following categories relate to this issue:
-
gdk-reliability - e.g. When a GDK action fails to complete. -
gdk-usability - e.g. Improvements or suggestions around how the GDK functions. -
gdk-performance - e.g. When a GDK action is slow or times out.
Steps to replicate (optional)
Proposal (optional)
Environment (optional)
- Operating system name:
<!-- output of `uname -a` command -->
- Architecture:
<!-- output of `arch` command -->
- The contents of your
gdk.yml
(if any) - Ruby version:
<!-- output of `ruby --version` command -->
- GDK version:
<!-- output of `git rev-parse --short HEAD` command -->