在 GitHub Actions 上集成

以下示例展示了如何将 Turborepo 与 GitHub Actions 一起使用。

对于给定的根 package.json：

./package.json

{
  "name": "my-turborepo",
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

以及一个 turbo.json：

./turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**", "other-output-dirs/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}

在你的仓库中创建一个名为 .github/workflows/ci.yml 的文件，内容如下：

.github/workflows/ci.yml

name: CI
 
on:
  push:
    branches: ["main"]
  pull_request:
    types: [opened, synchronize]
 
jobs:
  build:
    name: Build and Test
    timeout-minutes: 15
    runs-on: ubuntu-latest
    # 要使用远程缓存，取消注释下面的行并按照下面的步骤操作。
    # env:
    #  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    #  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
    #  TURBO_REMOTE_ONLY: true
 
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
 
      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
 
      - name: Install dependencies
        run: npm install
 
      - name: Build
        run: npm run build
 
      - name: Test
        run: npm run test

远程缓存

要在 GitHub Actions 中使用远程缓存，请将以下环境变量添加到你的 GitHub Actions 工作流中，使它们可用于你的 turbo 命令。

TURBO_TOKEN - 访问远程缓存的 Bearer 令牌
TURBO_TEAM - 单体仓库所属的账户

要使用远程缓存，请获取你的提供商的远程缓存的团队和令牌。在此示例中，我们将使用 Vercel 远程缓存。

在 Vercel 控制面板中为你的账户创建一个范围访问令牌

Vercel 访问令牌

将值复制到安全的地方。你稍后会需要它。

转到你的 GitHub 仓库设置，点击 Secrets 然后点击 Actions 标签。创建一个名为 TURBO_TOKEN 的新密钥，并输入你的范围访问令牌的值。

GitHub 密钥 GitHub 创建密钥

创建一个名为 TURBO_TEAM 的新仓库变量（点击 Variables 标签），并输入你的团队的 Vercel URL 值，不带 vercel.com/。使用仓库变量而不是密钥将防止 GitHub Actions 在日志输出中审查你的团队名称。

GitHub 仓库变量

你可以在控制面板的团队通用项目设置中找到你的团队 URL。如果你使用的是业余计划，可以使用你的用户名。你可以在 Vercel 个人账户设置中找到你的用户名

Vercel 账户标识

在你的 GitHub Actions 工作流的顶部，为使用 turbo 的作业提供以下环境变量：

.github/workflows/ci.yml

# ...
 
jobs:
  build:
    name: Build and Test
    timeout-minutes: 15
    runs-on: ubuntu-latest
    # 要使用 Turborepo 远程缓存，为作业设置以下环境变量。
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} // [!code highlight]
      TURBO_TEAM: ${{ vars.TURBO_TEAM }} // [!code highlight]
 
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
    # ...

使用 GitHub actions/cache 进行缓存

以下步骤示范了如何使用 actions/cache 在 GitHub 上缓存你的单体仓库构建产物。

提供一个使用 Turborepo 运行任务的 package.json 脚本。

带有 build 脚本的 package.json 示例：

./package.json

{
  "name": "my-turborepo",
  "scripts": {
    "build": "turbo run build"
  },
  "devDependencies": {
    "turbo": "1.2.5"
  }
}

在你的 CI 文件的构建步骤之前，配置你的 GitHub 流水线，使用 actions/cache@v4 动作。

确保在 actions/cache 动作中设置的 path 属性与上面的输出位置匹配。在下面的示例中，path 被设置为 .turbo。
在 key 属性下声明当前运行的缓存键。在下面的示例中，我们使用了运行器操作系统和 GitHub sha 的组合作为缓存键。
在 restore-keys 属性下声明所需的缓存前缀模式。确保此模式对未来的 CI 运行保持有效。在下面的示例中，我们使用 ${{ runner.os }}-turbo- 作为要搜索的缓存键前缀。这允许我们在任何后续的 CI 运行中命中缓存，尽管 github.sha 会发生变化。

选择 .turbo 作为缓存文件夹的 ci yaml 示例：

.github/workflows/ci.yml

  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
        - name: Check out code
          uses: actions/checkout@v4
 
        - name: Cache turbo build setup // [!code highlight]
          uses: actions/cache@v4 // [!code highlight]
          with:
            path: .turbo // [!code highlight]
            key: ${{ runner.os }}-turbo-${{ github.sha }} // [!code highlight]
            restore-keys: |
              ${{ runner.os }}-turbo- // [!code highlight]
 
        - name: Setup Node.js environment
          uses: actions/setup-node@v4
          with:
            node-version: 20
            cache: 'npm'
 
        - name: Install dependencies
          run: npm install
 
        - name: Build
          run: npm run build