GitHub Actions

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

¥The following example shows how to use Turborepo with GitHub Actions.

对于给定的根 package.json：

¥For a given root package.json:

./package.json

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

以及 turbo.json：

¥And a turbo.json:

./turbo.json

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

在你的代码库中创建一个名为 .github/workflows/ci.yml 的文件，其中包含以下内容：

¥Create a file called .github/workflows/ci.yml in your repository with the following contents:

.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
    # To use Remote Caching, uncomment the next lines and follow the steps below.
    # env:
    #  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    #  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
 
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
 
      - uses: pnpm/action-setup@v3
        with:
          version: 8
 
      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
 
      - name: Install dependencies
        run: pnpm install
 
      - name: Build
        run: pnpm build
 
      - name: Test
        run: pnpm test

使用 Vercel 远程缓存进行远程缓存

¥Remote Caching with Vercel Remote Cache

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

¥To use Remote Caching with GitHub Actions, add the following environment variables to your GitHub Actions workflow to make them available to your turbo commands.

TURBO_TOKEN - 用于访问远程缓存的 Bearer 令牌

¥TURBO_TOKEN - The Bearer token to access the Remote Cache
TURBO_TEAM - 代码库所属账户

¥TURBO_TEAM - The account to which the repository belongs

要使用远程缓存，请检索提供程序的远程缓存的团队和令牌。在此示例中，我们将使用 Vercel 远程缓存。

¥To use Remote Caching, retrieve the team and token for the Remote Cache for your provider. In this example, we'll use Vercel Remote Cache.

在 Vercel 仪表板中为你的账户创建一个作用域访问令牌

¥Create a Scoped Access Token to your account in the Vercel Dashboard

Vercel Access Tokens

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

¥Copy the value to a safe place. You'll need it in a moment.

转到 GitHub 仓库设置，然后点击“Secrets”选项卡，然后点击“Actions”选项卡。创建一个名为 TURBO_TOKEN 的新密钥，并输入你的作用域访问令牌的值。

¥Go to your GitHub repository settings and click on the Secrets and then Actions tab. Create a new secret called TURBO_TOKEN and enter the value of your Scoped Access Token.

GitHub Secrets

GitHub Secrets Create

创建一个名为 TURBO_TEAM 的新代码库变量（点击“变量”选项卡），并输入你的团队 URL。

¥Create a new repository variable (click the Variables tab) called TURBO_TEAM and enter your Team URL.

Good to know:

使用仓库变量而不是 secret 将阻止 GitHub Actions 在日志输出中屏蔽你的团队名称。

¥Using a repository variable rather than a secret will keep GitHub Actions from censoring your team name in log output.

GitHub Repository Variables

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

¥At the top of your GitHub Actions workflow, provide the following environment variables to jobs that use turbo:

.github/workflows/ci.yml

# ...
 
jobs:
  build:
    name: Build and Test
    timeout-minutes: 15
    runs-on: ubuntu-latest
    # To use Turborepo Remote Caching, set the following environment variables for the job.
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
 
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
    # ...

使用 GitHub actions/cache 进行远程缓存

¥Remote Caching with GitHub actions/cache

以下步骤展示了如何使用 actions/cache 在 GitHub 上缓存你的 monorepo 工件。

¥The following steps show how you could use actions/cache to cache your monorepo artifacts on GitHub.

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

¥Supply a package.json script that will run tasks using Turborepo.

示例 package.json 和 build 脚本：

¥Example package.json with a build script:

./package.json

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

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

¥Configure your GitHub pipeline with a step which uses the actions/cache@v4 action before the build steps of your CI file.

确保 actions/cache 操作中设置的 path 属性与上面的输出位置匹配。在下面的示例中，path 设置为 .turbo。

¥Make sure that the path attribute set within the actions/cache action matches the output location above. In the example below, path was set to .turbo.
在 key 属性下声明当前运行的缓存键。在下面的示例中，我们使用运行器操作系统和 GitHub SHA 的组合作为缓存键。

¥State the cache key for the current run under the key attribute. In the example below, we used a combination of the runner os and GitHub sha as the cache key.
在 restore-keys 属性下声明所需的缓存前缀模式。确保此模式在未来的 CI 运行中仍然有效。在下面的示例中，我们使用 ${{ runner.os }}-turbo- 作为缓存键前缀模式进行搜索。这允许我们在任何后续 CI 运行中访问缓存，即使 github.sha 发生变化。

¥State the desired cache prefix pattern under the restore-keys attribute. Make sure this pattern will remain valid for future ci runs. In the example below, we used the ${{ runner.os }}-turbo- as the cache key prefix pattern to search against. This allows us to hit the cache on any subsequent ci runs despite github.sha changing.

示例 ci yaml 文件，其中 .turbo 为选定的缓存文件夹：

¥Example ci yaml with .turbo as chosen cache folder:

.github/workflows/ci.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4
 
      - name: Cache turbo build setup
        uses: actions/cache@v4
        with:
          path: .turbo
          key: ${{ runner.os }}-turbo-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-
 
      - 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