在多R包单体仓库子目录配置GitHub Actions的方案问询

问题描述 #

我平时编写R包时，习惯用usethis::use_github_actions()在仓库根目录创建.github/目录配置CI（持续集成）。现有一个遗留仓库，其/R目录下包含多个R包，其他目录还存有Python应用等内容，希望为每个R包单独配置持续集成，且无需将各包迁移至独立仓库。请问如何配置GitHub Actions工作流以分别检查/R目录下的每个R包？此类仓库结构下，能否使用usethis工具创建徽章、pkgdown网站等？

一、配置GitHub Actions实现多R包独立CI #

1. 静态指定包的工作流方案 #

在仓库根目录的.github/workflows/下创建r-package-checks.yml文件，利用矩阵策略（matrix）为每个R包单独执行CI检查：

name: 多R包持续集成检查

on:
  push:
    paths:
      - "R/**"
  pull_request:
    paths:
      - "R/**"

jobs:
  check-package:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        package: ["scales", "roxygen2"] # 对应/R下的包目录名称
        r-version: ["release"]

    steps:
      - name: 拉取仓库代码
        uses: actions/checkout@v4

      - name: 配置R环境
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: ${{ matrix.r-version }}

      - name: 安装包依赖
        uses: r-lib/actions/setup-r-dependencies@v2
        with:
          working-directory: ./R/${{ matrix.package }}
          extra-packages: any::rcmdcheck
          needs: check

      - name: 执行R包检查
        uses: r-lib/actions/check-r-package@v2
        with:
          working-directory: ./R/${{ matrix.package }}

2. 动态遍历包目录的自动化方案 #

如果/R下的包数量较多或会新增，可通过前置任务自动识别所有包目录，无需手动维护矩阵列表：

name: 动态多R包CI检查

on: [push, pull_request]

jobs:
  discover-packages:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.set-packages.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
      - id: set-packages
        run: |
          # 遍历/R下的所有子目录（排除/R本身），转为JSON格式传递给矩阵
          PACKAGES=$(find R -maxdepth 1 -type d | grep -v "^R$" | sed 's/R\///' | jq -R . | jq -s .)
          echo "packages=$PACKAGES" >> $GITHUB_OUTPUT

  check-package:
    needs: discover-packages
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        package: ${{ fromJson(needs.discover-packages.outputs.packages) }}
        r-version: ["release"]

    steps:
      - name: 拉取仓库代码
        uses: actions/checkout@v4

      - name: 配置R环境
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: ${{ matrix.r-version }}

      - name: 安装包依赖
        uses: r-lib/actions/setup-r-dependencies@v2
        with:
          working-directory: ./R/${{ matrix.package }}
          extra-packages: any::rcmdcheck
          needs: check

      - name: 执行R包检查
        uses: r-lib/actions/check-r-package@v2
        with:
          working-directory: ./R/${{ matrix.package }}

二、usethis工具的适配使用 #

1. 创建CI徽章 #

usethis支持为单个包添加徽章，但需先切换到对应包的目录并设置项目上下文：

# 进入目标包目录后执行
usethis::proj_set("./R/scales") # 替换为你的包路径
# 从GitHub Actions工作流页面复制对应包的徽章URL，填入下方
usethis::use_badge("CI", "https://github.com/<你的用户名>/<仓库名>/actions/workflows/r-package-checks.yml/badge.svg?package=scales")

2. 构建pkgdown网站 #

可为每个R包单独构建pkgdown网站，步骤如下：

1. 切换到包目录，初始化pkgdown配置：

usethis::proj_set("./R/scales")
usethis::use_pkgdown()

2. 在GitHub Actions工作流中添加pkgdown构建步骤（可插入到包检查步骤之后）：

- name: 构建pkgdown网站
  uses: r-lib/actions/pkgdown@v2
  with:
    working-directory: ./R/${{ matrix.package }}
  env:
    GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

部署时可将每个包的pkgdown输出目录指定为根目录的docs/<包名>，再配置GitHub Pages从docs目录读取，访问路径为https://<用户名>.github.io/<仓库名>/<包名>。

复现示例的macOS Shell命令 #

mkdir example_repo
cd example_repo
git clone https://github.com/r-lib/scales.git
git clone https://github.com/r-lib/roxygen2
cd roxygen2
rm -rf .git
cd ../scales
rm -rf .git

内容的提问来源于stack exchange，提问作者Michael Roswell