Ruby 项目如何配置 GitHub Actions：从基础 CI 到多版本测试

Evan

发布时间：2026-08-25| 141人浏览过

原创

前言

对很多 Ruby 项目来说，接入 GitHub Actions 的难点不在“会不会写 YAML”，而在于先把一条可靠的构建与测试链路搭起来。本文按实际落地顺序整理出最小可用配置，再补上环境变量和多版本矩阵，方便你判断哪些内容适合直接照用，哪些适合后续扩展。

对 Ruby 项目来说，接入 GitHub Actions 的核心目标通常不是“把 YAML 写出来”，而是尽快形成一条稳定、能重复执行的构建与测试流程。下面就按实际配置顺序，从项目准备、首个工作流，到环境变量和多版本矩阵测试，整理出一套适合入门和后续扩展的配置思路。

开始前要准备什么

在配置 GitHub Actions 之前，先确保手里已经有一个可推送到 GitHub 的 Ruby 项目仓库。仓库可以是公开的，也可以是私有的，具体取决于项目本身的协作和发布需求。

创建并初始化本地项目

如果你还没有现成项目，可以先在本地初始化一个最小示例仓库：

mkdir my-ruby-app
cd my-ruby-app
git init

接着添加一个基础 Gemfile，用来声明 Ruby 依赖：

source 'https://rubygems.org'

gem 'rails', '~> 6.0'

然后安装依赖：

bundle install

这一阶段的重点很简单：先保证项目本地能正常安装依赖、执行后续测试命令。因为 GitHub Actions 只是把这些步骤搬到远程执行，如果本地流程本身不通，CI 配置也很难稳定。

GitHub Actions 在 Ruby 项目里怎么工作

它解决的是什么问题

GitHub Actions 是 GitHub 提供的 CI/CD 工具，可以在代码推送、发起拉取请求等事件发生后，自动执行构建、测试甚至部署任务。对 Ruby 项目而言，最常见的起点就是：有人向 main 分支提交代码后，自动安装依赖并运行测试。

工作流文件放在哪里

GitHub Actions 的配置文件是 YAML 格式，通常放在仓库的 .github/workflows/ 目录下。比如，一个 Ruby 项目常见的配置文件名就是 ruby.yml。

展示 GitHub Actions 中环境变量与构建矩阵的配置对比图 — **环境变量与多版本测试的分工**将环境变量和 Ruby 版本矩阵放在同一张对比图中。

也就是说，只要仓库里存在 .github/workflows/ruby.yml，GitHub 就会在匹配的触发条件下读取它，并按其中定义的任务顺序运行。

第一个 Ruby 工作流怎么写

如果你想先把最基本的 CI 跑起来，可以直接新建 .github/workflows/ruby.yml，再写入下面这份配置：

展示 Ruby CI 工作流从触发到测试执行的步骤关系图 — **Ruby CI 基础工作流结构**用流程图梳理首个 Ruby CI 工作流的触发条件、执行环境与核心步骤，便于快速理解 YAML。

name: Ruby CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 2.7
    - name: Install dependencies
      run: bundle install --jobs 4 --retry 3
    - name: Run tests
      run: bundle exec rspec

这份配置已经覆盖了一个 Ruby 项目最常见的 CI 主线：拉取代码、准备 Ruby 运行环境、安装依赖、执行测试。

几个关键字段分别代表什么

name：工作流名称，会显示在 GitHub Actions 页面里。
on：定义触发条件。这里选择的是 push 和 pull_request，并限定在 main 分支触发。
jobs：定义要执行的任务。一个工作流可以包含多个任务。
runs-on：指定任务运行环境，这里是 ubuntu-latest。
steps：任务内部的执行步骤，每一步都是一个明确动作。

其中，actions/checkout@v2 负责把仓库代码签出到运行环境；ruby/setup-ruby@v1 用来安装并切换指定 Ruby 版本；bundle install --jobs 4 --retry 3 则是 Ruby 项目里常见的依赖安装方式，带有并发和重试参数，适合在 CI 环境中使用。

如果你的项目测试命令不是 bundle exec rspec，这里也应该替换成实际使用的命令。CI 配置本质上只是把团队已有的构建和测试过程声明出来，而不是另起一套流程。

环境变量应该怎么放进工作流

很多 Ruby 项目在测试时都需要明确运行环境。GitHub Actions 支持在工作流中声明环境变量，供后续步骤统一读取，这样能减少命令硬编码，也更便于后续维护。

设置环境变量

例如，可以在工作流中加入：

env:
  RAILS_ENV: test

这样一来，RAILS_ENV 就能在整个工作流范围内访问。

在步骤中引用变量

定义好之后，就可以在测试步骤中直接使用：

- name: Run tests
  run: bundle exec rspec --environment ${{ env.RAILS_ENV }}

这种写法的好处在于，测试环境的取值集中管理，后续调整时不需要逐条修改命令。对于包含多个测试步骤、脚本或部署动作的项目，这一点尤其重要。

需要兼容多个 Ruby 版本时怎么做

如果你的项目需要同时支持多个 Ruby 版本，单跑一个固定版本往往不够。GitHub Actions 提供的构建矩阵可以把一套流程扩展为多组环境并行执行，这也是 Ruby 库和长期维护项目中很常见的配置方式。

构建矩阵示例

下面这份配置展示了如何让同一组测试分别在 Ruby 2.6 和 2.7 上运行：

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        ruby-version: [2.6, 2.7]
    steps:
    - uses: actions/checkout@v2
    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: ${{ matrix.ruby-version }}
    - name: Install dependencies
      run: bundle install --jobs 4 --retry 3
    - name: Run tests
      run: bundle exec rspec

这里的关键变化有两个：