如何在推送之前在本地运行 GitHub Actions 和 GitLab CI

您可以在自己的计算机上使用 `act` 运行 GitHub Actions，并使用 gitlab-ci-local 在自己的计算机上运行 GitLab CI：两者都会读取管道文件并启动 Docker 容器中的每个作业。 安装 Docker，安装运行程序，然后从存储库的文件夹运行 act -j test 或 gitlab-ci-local test。现在，失败的作业会在您的计算机上几秒钟内失败，而不是在推送并等待托管运行程序之后失败。

本指南介绍了在 macOS、Windows 和 Linux 上安装的内容、两个运行程序的命令、您可以复制的示例工作流程、本地运行的限制以及人们首先遇到的错误。本演练使用我们制作的 Git 客户端 GitTree：其 本地管道 页面检查您已安装的内容，编写示例文件并为您准备准确的命令。本地管道是 GitTree 免费计划的一部分，不需要托管帐户。

为什么要在本地运行 CI 管道？

对工作流文件的每次更改都是代码，在运行之前您无法对其进行测试。如果没有本地运行程序，循环是：编辑 YAML、提交、推送、等待运行程序、读取日志、重​​复。每一轮都会花费几分钟的时间，并留下诸如“再试一次”之类的提交痕迹。本地运行将循环缩短到几秒，并保持历史记录干净。

您需要什么：Docker 加上一名跑步者

两个运行器都会启动容器中的每个作业，因此必须安装并运行 Docker 引擎：Docker Desktop、OrbStack 或 Colima 在 macOS 上、Docker Desktop 在 Windows 上、Docker Engine 或 Docker Desktop 在 Linux 上运行。然后为您的文件安装运行程序。

当您使用 npm 安装时，gitlab-ci-local 需要 Node.js 18 或更高版本。检查 docker info、act --version 和 gitlab-ci-local --version 的设置：如果 docker info 失败，请先启动引擎。

使用 act 在本地运行 GitHub Actions

从存储库的根文件夹运行 act。首先列出作业，然后运行您正在处理的作业。默认情况下，act 模拟 push 事件，因此仅在其他事件上运行的作业需要事件名称。

# list workflows and jobs
act -l

# run one job from one workflow file
act -W .github/workflows/ci.yml -j test

# simulate a pull request instead of a push
act pull_request -j test

# pass a secret the job needs
act -j deploy -s NPM_TOKEN="$NPM_TOKEN"

# Apple silicon: run x86_64 images
act -j test --container-architecture linux/amd64

第一次运行询问要使用哪个跑步者图像。 中适合大多数项目；小图像缺少托管跑步者所包含的工具，并且完整图像非常大。如果某个步骤因“找不到命令”而失败，请使用 -P ubuntu-latest=<image> 选择更大的图像或在步骤中安装该工具。

使用 gitlab-ci-local 在本地运行 GitLab CI

gitlab-ci-local 从当前文件夹读取 .gitlab-ci.yml。没有任何参数，它运行整个管道；为其指定一个作业名称来运行一项作业。 --list 显示作业而不运行它们，这是检查 YAML 解析的快速方法。

# list jobs and stages
gitlab-ci-local --list

# run one job
gitlab-ci-local test

# pass a CI/CD variable
gitlab-ci-local test --variable API_URL=http://localhost:8080

可以从以下示例工作流程开始

这是 GitTree 的 GitHub Actions 示例的形式：两个作业，构建然后测试，在 act 和 GitHub 上的工作方式相同。将命令替换为您自己的命令。

name: GitTree local check

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test

本地运行与托管 CI 有何不同

• 在 GitHub 或 GitLab 上配置的秘密和变量不可用；通过工作所需的那些。
• 容器，而不是虚拟机：需要 systemd 或完整虚拟机的服务不会以相同的方式运行。
• 图像与托管跑步者不同；缺少工具只是缺少软件包，而不是工作流程损坏。
• 事件是模拟的：act 默认为 push；可重用的工作流程、包含内容和模板由运行者解析，而不是由编辑器解析。
• 通过的本地运行不是托管结果：它缩短了循环；您的主人仍然拥有最终决定权。

常见错误和修复

推送之前：预测冲突、检查机密、预览推送

本地管道运行回答了一个问题：工作是否会通过。其他三个检查会捕获 CI 延迟报告或根本未报告的内容，并且每个检查也会在发送任何内容之前在您的计算机上运行。

1. 预测合并。 git merge-tree --write-tree --name-only HEAD origin/main 在内存中合并并列出会发生冲突的文件，而不触及您的工作树。 GitTree 进行相同类型的检查，并在可能发生冲突的合并之前发出警告；请参阅如何解决 Git 合并冲突。
2. 检查机密。 在提交或推送之前，GitTree 会在本地扫描更改以查找可能的令牌、密码和私钥，如果找到，则停止并显示一个对话框。到达远程仓库的秘密必须轮换，因此捕获秘密的最便宜的时刻是在推送之前。警告并不能保证，因此请务必检查您发送的内容。
3. 预览推送。发布预览列出了推送将发送的提交和文件，以及对于它可以读取的每个工作流文件，管道是否在此推送上将运行、可能运行或不会运行，并附有原因。

然后在本地运行作业并推送一次。 秘密警告指南 和发布预览指南 详细介绍了这两个对话框。

Bitbucket Pipelines 和 Azure Pipelines 怎么样？

没有维护与 act 或 gitlab-ci-local 匹配的 bitbucket-pipelines.yml 或 azure-pipelines.yml 本地运行程序。一种实用的方法是将构建和测试命令保留在脚本中，从托管管道中调用它们，并添加一个仅用于本地运行的小 GitHub Actions 或 GitLab CI 文件。 GitTree 标记这些文件 没有本地运行程序 并提供了具体的示例。

后续步骤：本地运行管道指南 记录了每个按钮，CI/CD 运行 涵盖托管运行、重新运行和批准，工具启动器 列出了 GitTree 的其他内置工具。