注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。
简介
本指南介绍如何创建用来生成和测试 Ruby 应用程序的持续集成 (CI) 工作流程。 如果 CI 测试通过,您可能想要部署代码或发布 gem。
先决条件
建议基本了解 Ruby、YAML、工作流程配置选项以及如何创建工作流程文件。 有关详细信息,请参阅:
使用 Ruby 工作流模板
若要快速开始使用,请将工作流模板添加到存储库的 .github/workflows
目录。
GitHub 为 Ruby 提供了一个工作流模板,适用于大多数 Ruby 项目。 本指南的后续部分提供了如何自定义此工作流模板的示例。
-
在 你的 GitHub Enterprise Server 实例 上,导航到存储库的主页。
-
在存储库名称下,单击 “操作”。
-
如果存储库中已有工作流,请单击“新建工作流”。
-
“选择工作流”页面显示一系列推荐的工作流模板。 搜索“ruby”。
-
单击“持续集成”**** 以筛选工作流选择。
-
在“Ruby”工作流上,单击“配置”。
如果未找到“Ruby”工作流模板,请将以下工作流代码复制到存储库的
.github/workflows
目录中名为ruby.yml
的新文件。YAML name: Ruby on: push: branches: [ "main" ] pull_request: branches: [ "main" ] permissions: contents: read jobs: test: runs-on: ubuntu-latest strategy: matrix: ruby-version: ['2.6', '2.7', '3.0'] steps: - uses: actions/checkout@v4 - name: Set up Ruby # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby, # change this to (see https://github.com/ruby/setup-ruby#versioning): # uses: ruby/setup-ruby@v1 uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0 with: ruby-version: ${{ matrix.ruby-version }} bundler-cache: true # runs 'bundle install' and caches installed gems automatically - name: Run tests run: bundle exec rake
name: Ruby on: push: branches: [ "main" ] pull_request: branches: [ "main" ] permissions: contents: read jobs: test: runs-on: ubuntu-latest strategy: matrix: ruby-version: ['2.6', '2.7', '3.0'] steps: - uses: actions/checkout@v4 - name: Set up Ruby # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby, # change this to (see https://github.com/ruby/setup-ruby#versioning): # uses: ruby/setup-ruby@v1 uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0 with: ruby-version: ${{ matrix.ruby-version }} bundler-cache: true # runs 'bundle install' and caches installed gems automatically - name: Run tests run: bundle exec rake
-
根据需要编辑工作流。 例如更改要使用的 Ruby 版本。
注意:
- 此工作流模板包含未通过 GitHub 认证的操作。 第三方提供的操作受单独的服务条款、隐私政策和支持文档管辖。
- 如果使用来自第三方的操作,则应使用提交 SHA 指定的版本。 如果操作已被修改,并且需要使用较新版本,则需要更新 SHA。 可以通过引用标记或分支来指定版本,但操作可能会在没有事先警告的情况下更改。 有关详细信息,请参阅“GitHub Actions 的安全强化”。
-
单击“提交更改”。
指定 Ruby 版本
指定 Ruby 版本的最简单方法是使用 GitHub 上的 Ruby 组织提供的 ruby/setup-ruby
操作。 对于工作流中运行的每个作业,该操作会将任何受支持的 Ruby 版本添加到 PATH
。 有关详细信息和可用的 Ruby 版本,请参阅 ruby/setup-ruby
。
使用 Ruby 的 ruby/setup-ruby
操作是将 Ruby 与 GitHub Actions 结合使用的推荐方式,因为它能确保不同运行器和不同版本的 Ruby 行为一致。
setup-ruby
操作将 Ruby 版本作为输入并在运行器上配置该版本。
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
ruby-version: '3.1' # Not needed with a .ruby-version file
- run: bundle install
- run: bundle exec rake
也可将 .ruby-version
文件签入存储库的根目录,setup-ruby
将使用该文件中定义的版本。
使用多个版本的 Ruby 进行测试
您可以添加矩阵策略,以在多个版本的 Ruby 上运行工作流程。 例如,您可以根据版本 3.1、3.0 和 2.7 的最新修补程序版本测试代码。
strategy:
matrix:
ruby-version: ['3.1', '3.0', '2.7']
ruby-version
数组中指定的每个 Ruby 版本都会创建一个运行相同步骤的作业。 ${{ matrix.ruby-version }}
上下文用于访问当前作业的版本。 有关矩阵策略和上下文的详细信息,请参阅“GitHub Actions 的工作流语法”和“访问有关工作流运行的上下文信息”。
包含矩阵策略的完整更新工作流程可能看起如下:
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。
# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。
name: Ruby CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
ruby-version: ['3.1', '3.0', '2.7']
steps:
- uses: actions/checkout@v4
- name: Set up Ruby ${{ matrix.ruby-version }}
uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
ruby-version: ${{ matrix.ruby-version }}
- name: Install dependencies
run: bundle install
- name: Run tests
run: bundle exec rake
使用 Bundler 安装依赖项
setup-ruby
操作将自动安装捆绑程序。 版本由 gemfile.lock
文件决定。 如果您的锁定文件中没有版本,则会安装最新的兼容版本。
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
ruby-version: '3.1'
- run: bundle install
缓存依赖项
setup-ruby
操作提供在运行之间自动处理 Gem 缓存的方法。
要启用缓存,请设置以下内容。
steps:
- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
bundler-cache: true
这将配置捆绑程序以将 gem 安装到 vendor/cache
。 对于工作流的每次成功运行,此文件夹将由 GitHub Actions 缓存,并重新下载用于后续的工作流运行。 gemfile.lock 和 Ruby 版本的哈希值用作缓存密钥。 如果安装任何新 Gem 或更改版本,缓存将失效,Bundler 将进行全新安装。
不使用 setup-ruby 进行缓存
为了更好地控制缓存,可以直接使用 actions/cache
操作。 有关详细信息,请参阅“缓存依赖项以加快工作流程”。
steps:
- uses: actions/cache@v3
with:
path: vendor/bundle
key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
restore-keys: |
${{ runner.os }}-gems-
- name: Bundle install
run: |
bundle config path vendor/bundle
bundle install --jobs 4 --retry 3
如果您使用的是矩阵构建,您将会想要在缓存密钥中包含矩阵变量。 例如,如果提供了针对不同 Ruby 版本 (matrix.ruby-version
) 和不同操作系统 (matrix.os
) 的矩阵策略,工作流步骤可能如下所示:
steps:
- uses: actions/cache@v3
with:
path: vendor/bundle
key: bundle-use-ruby-${{ matrix.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
restore-keys: |
bundle-use-ruby-${{ matrix.os }}-${{ matrix.ruby-version }}-
- name: Bundle install
run: |
bundle config path vendor/bundle
bundle install --jobs 4 --retry 3
测试代码的矩阵
下面的示例矩阵在 Ubuntu 和 macOS 上测试 MRI、JRuby 和 TruffleRuby 的所有稳定版本和头部版本。
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。
# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。
name: Matrix Testing
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ${{ matrix.os }}-latest
strategy:
fail-fast: false
matrix:
os: [ubuntu, macos]
ruby: [2.5, 2.6, 2.7, head, debug, jruby, jruby-head, truffleruby, truffleruby-head]
continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
ruby-version: ${{ matrix.ruby }}
- run: bundle install
- run: bundle exec rake
嵌入代码
以下示例安装 rubocop
并使用它对所有文件进行 lint 操作。 有关详细信息,请参阅 RuboCop。 可以配置 Rubocop 以决定具体的 Lint 分析规则。
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。
# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。
name: Linting
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
ruby-version: '2.6'
- run: bundle install
- name: Rubocop
run: rubocop -f github
指定 -f github
意味着 RuboCop 输出将为 GitHub 的批注格式。 任何 Lint 分析错误都会在引入它们的拉取请求的已更改的文件选项卡中内联显示。
发布 Gem
您可以配置工作流程在 CI 测试通过时将 Ruby 包发布到您想要的任何包注册表。
您可以使用仓库密码存储发布软件包所需的访问令牌或凭据。 以下示例创建包并将其发布到 GitHub Package Registry
和 RubyGems
。
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。
# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。
name: Ruby Gem
on:
# Manually publish
workflow_dispatch:
# Alternatively, publish whenever changes are merged to the `main` branch.
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
name: Build + Publish
runs-on: ubuntu-latest
permissions:
packages: write
contents: read
steps:
- uses: actions/checkout@v4
- name: Set up Ruby 2.6
uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
with:
ruby-version: '2.6'
- run: bundle install
- name: Publish to GPR
run: |
mkdir -p $HOME/.gem
touch $HOME/.gem/credentials
chmod 0600 $HOME/.gem/credentials
printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
gem build *.gemspec
gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
env:
GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
OWNER: ${{ github.repository_owner }}
- name: Publish to RubyGems
run: |
mkdir -p $HOME/.gem
touch $HOME/.gem/credentials
chmod 0600 $HOME/.gem/credentials
printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
gem build *.gemspec
gem push *.gem
env:
GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"