CircleCI提示Could not locate Gemfile错误修复及Ruby Gem项目CI配置

我的Ruby Gem项目目录结构如下：

- org-lib
  - .circleci
  - ticketing
    - ticket-management

Gemfile、Gemfile.lock及所有测试代码都存放在ticket-management目录中。当前CircleCI配置文件如下：

version: 2.1
jobs:
 ticket-management-job:
    working_directory: ~/ticketing/ticket-management
    docker:
      - image: circleci/ruby:3.0.1
    steps:
      - checkout
      - run:
          name: "Install Bundle"
          command: "bundle install"
      - run:
          name: "Run Test"
          command: "bundle exec rspec spec/ticket_management_spec.rb"
workflows:
  ticket-management-workflow:
    jobs:
      - ticket-management-job

推送后出现错误：

bundle install
Could not locate Gemfile

Exited with code exit status 10
CircleCI received exit code 10

请问如何修复该错误？Ruby Gem项目应如何正确配置CI？

一、报错原因及快速修复 #

报错核心原因：checkout步骤会将整个仓库代码拉取到CircleCI默认工作目录~/project，但你设置的working_directory是~/ticketing/ticket-management，该路径与实际代码存放路径不匹配，导致执行bundle install时找不到Gemfile。

方法1：调整工作目录为实际路径 #

修改working_directory指向仓库内的ticket-management目录：

version: 2.1
jobs:
 ticket-management-job:
    # 修正为仓库拉取后的实际路径
    working_directory: ~/project/ticketing/ticket-management
    docker:
      - image: circleci/ruby:3.0.1
    steps:
      - checkout
      - run:
          name: "Install Bundle"
          command: "bundle install"
      - run:
          name: "Run Test"
          command: "bundle exec rspec spec/ticket_management_spec.rb"
workflows:
  ticket-management-workflow:
    jobs:
      - ticket-management-job

方法2：执行命令前切换目录 #

若不想修改工作目录，可在run步骤中先切换到Gemfile所在目录：

version: 2.1
jobs:
 ticket-management-job:
    working_directory: ~/ticketing/ticket-management
    docker:
      - image: circleci/ruby:3.0.1
    steps:
      - checkout
      - run:
          name: "Install Bundle"
          command: "cd ~/project/ticketing/ticket-management && bundle install"
      - run:
          name: "Run Test"
          command: "cd ~/project/ticketing/ticket-management && bundle exec rspec spec/ticket_management_spec.rb"
workflows:
  ticket-management-workflow:
    jobs:
      - ticket-management-job

二、Ruby Gem项目CircleCI最佳配置实践 #

1. 精准设置工作目录
   确保working_directory指向仓库中Gemfile所在的实际路径，后续所有步骤默认在该目录执行，无需重复切换路径。

2. 缓存bundle依赖
   添加缓存步骤避免重复安装gem，提升CI执行速度：

   steps:
     - checkout
     - restore_cache:
         keys:
           - gem-cache-{{ checksum "Gemfile.lock" }}
           - gem-cache-
     - run: bundle install --path vendor/bundle
     - save_cache:
         paths:
           - vendor/bundle
         key: gem-cache-{{ checksum "Gemfile.lock" }}
   

3. 完善质量校验流程
   除测试外，添加代码lint、gem构建等步骤，保障gem质量：

   - run:
       name: "Run Rubocop Lint"
       command: "bundle exec rubocop"
   - run:
       name: "Build Gem"
       command: "gem build your_gem_name.gemspec"
   

4. 匹配Ruby版本镜像
   使用与项目一致的Ruby版本镜像，避免版本兼容问题，例如项目用Ruby 3.2.2则选择circleci/ruby:3.2.2。

5. 并行化测试（可选）
   测试用例较多时，拆分测试到多个容器并行执行，缩短总耗时：

   - run:
       name: "Split Tests"
       command: |
         bundle exec rspec --format progress --no-color --dry-run spec/ | circleci tests split --split-by=timings > split_tests.txt
   - run:
       name: "Run Parallel Tests"
       command: bundle exec rspec --format progress $(cat split_tests.txt)
   

内容的提问来源于stack exchange，提问作者Dedy Puji