GitHub Actions 构建与测试 - CI/CD 基础教程

介绍

在现代软件开发中，持续集成（CI）是一项至关重要的实践，开发者需要频繁地将他们的代码变更合并到一个中央仓库中。自动化构建和测试会运行以验证这些变更。

GitHub Actions 是一个流行的 CI/CD 平台，它允许你直接在 GitHub 内部自动化你的构建、测试和部署流程。

在这个 Lab 中，你将学习如何为一个 Node.js 项目创建一个基本的 GitHub Actions 工作流（workflow）。你将定义步骤来设置 Node.js 环境、安装依赖项并运行测试。最后，你将提交（commit）并将这些更改推送到（push）你的 GitHub 仓库。

这个 Lab 基于你在之前的 Labs 中创建的仓库。你将克隆 github-actions-demo 仓库并为一个 Node.js 项目创建一个 CI 工作流。

到这个 Lab 结束时，你将理解 .yml 工作流文件的结构以及如何配置必要的 CI 步骤。

使用 uses actions/setup-node@v4 添加 Node.js 设置

在这一步，你将克隆（clone）仓库并创建一个带有 Node.js 环境设置的工作流（workflow）文件。GitHub Actions 工作流定义在仓库的 .github/workflows 目录下的 YAML 文件中。

在你的 github-actions-demo 的 GitHub 仓库页面上，点击绿色的 Code 按钮。
确保选择了 HTTPS 标签页，并复制该 URL。它看起来应该像 https://github.com/your-username/github-actions-demo.git。
在 LabEx 环境中打开终端。默认路径是 ~/project。
使用 git clone 命令下载仓库。将 your-username 替换为你实际的 GitHub 用户名。

cd ~/project
git clone https://github.com/your-username/github-actions-demo.git

cd ~/project/github-actions-demo

在 .github/workflows 目录下创建一个名为 node-ci.yml 的新文件：

touch .github/workflows/node-ci.yml

在 WebIDE 中打开 .github/workflows/node-ci.yml，首先添加工作流名称和触发器：

name: Node.js CI

on: [push]

添加 jobs（任务）部分，并定义 build 任务及其运行器（runner）：

jobs:
  build:
    runs-on: ubuntu-latest

添加 steps（步骤）部分。首先，添加 checkout 步骤以下载仓库代码：

steps:
  - uses: actions/checkout@v4

添加 Node.js 设置步骤：

- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "20"

现在你的完整文件应该如下所示：

name: Node.js CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

解释

name: 工作流的名称。
on: [push]: 每当有代码被推送到仓库时触发工作流。
jobs: 将在工作流中运行的所有任务组合在一起。
runs-on: ubuntu-latest: 配置任务在 GitHub 托管的、运行最新 Ubuntu 版本的虚拟机上执行。
steps: 一系列任务。
uses: actions/checkout@v4: 检出（checks out）你的仓库，以便工作流可以访问它。
uses: actions/setup-node@v4: 这是在运行器（runner）上安装 Node.js 的官方 Action。我们指定版本 '20'。

添加使用 run npm install 安装依赖的步骤

现在环境已经使用 Node.js 设置完毕，在持续集成（CI）流程中的下一步自然是安装项目的依赖项。这确保了在构建或测试之前，应用程序所需的所有外部库都可用。

再次打开 .github/workflows/node-ci.yml 文件，并添加安装依赖项的步骤。

将以下行添加到 steps 部分的末尾（请确保保持缩进）：

- name: Install dependencies
  run: npm install

你完整的 .github/workflows/node-ci.yml 文件现在应该如下所示：

name: Node.js CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Install dependencies
        run: npm install

解释

run: npm install: 这会在 runner 的 shell 中执行 npm install 命令。它会读取 package.json 文件（我们稍后会创建）并安装其中列出的依赖项。

添加使用 run npm test 运行测试的步骤

安装依赖项后，持续集成（Continuous Integration）中最关键的部分是运行自动化实验。这确保了新的更改不会破坏现有功能。

打开 .github/workflows/node-ci.yml 文件，并在其中追加运行实验的步骤。

将以下行添加到 steps 部分的末尾：

- name: Run tests
  run: npm test

你最终的 .github/workflows/node-ci.yml 文件应如下所示：

name: Node.js CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

解释

run: npm test: 这会执行在你的 package.json 中定义的实验脚本。如果实验失败（以非零代码退出），GitHub Action 工作流将被标记为失败。

创建 package.json 和简单的测试文件

为了我们刚刚创建的工作流能够真正运行，我们需要一个 Node.js 项目结构。具体来说，npm install 需要一个 package.json 文件，而 npm test 需要定义一个测试脚本。

cd ~/project/github-actions-demo

在仓库根目录创建一个 package.json 文件：

touch package.json

打开 package.json 并添加以下内容。这定义了一个基础项目和一个总是通过（以代码 0 退出）的简单测试脚本。

{
  "name": "github-actions-demo",
  "version": "1.0.0",
  "description": "Demo project",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Running tests...\" && exit 0"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

接下来，我们更新 index.js 以代表我们的应用代码。

echo "console.log('Hello, GitHub Actions!');" > index.js

现在你拥有了一个满足我们定义的工作流要求的最小 Node.js 项目：

npm install 将会运行（即使没有依赖项，它也会检查 package.json）。
npm test 将会运行命令 echo "Running tests..." && exit 0。

提交、推送并在工作流运行中验证构建/测试

现在我们已经创建了工作流定义和项目文件，我们需要将它们提交（commit）并推送到（push）GitHub。推送这些提交将触发 Action runner 来执行我们定义好的步骤。

cd ~/project/github-actions-demo

检查你仓库的状态：

git status

将所有文件添加到暂存区（staging area）：

git add .

使用描述性的消息提交更改：

git commit -m "Add Node.js CI workflow and project files"

将更改推送到 GitHub 上的远程仓库：

git push

关于身份验证的注意事项： 当你运行 git push 时，WebIDE 会自动提示你进行身份验证。请遵循以下详细步骤：

会弹出一个提示框，显示消息：**"The extension 'GitHub' wants to sign in using GitHub."** 点击 Allow。
会出现一个新的通知。点击 **"Copy&Continue to GitHub"**，然后在下一个提示中点击 **"Open"**。
在打开的浏览器窗口中登录你的 GitHub 账户，并输入被复制的授权码。确认授权后，页面将自动关闭。
等待几秒钟，你将看到终端成功完成推送操作。

隐私声明： WebIDE 会请求对你的 GitHub 账户的完全访问权限以进行身份验证。你无需担心隐私问题——在当前实验（lab）完成后，LabEx 虚拟机将立即销毁，你的凭证和授权信息不会被保留。

验证工作流运行

在网页浏览器中访问你的仓库：https://github.com/your-username/github-actions-demo
点击仓库页面顶部的 Actions 标签页。
你应该会看到一个工作流运行（workflow run）的列表，其名称可能为 "Add Node.js CI workflow and project files" 或 "Node.js CI"。

注意： 当你推送代码时，如果仓库中有多个工作流文件，可能会触发多个 Actions。请通过检查左侧边栏中的工作流名称或使用右侧的工作流运行列表来识别正确的工作流运行。

点击工作流运行的标题，然后点击 build 任务以查看详细的日志。

你可以展开每个步骤来查看发生了什么：

Checkout code: 显示仓库已被检出
Use Node.js: 显示 Node.js v20 已安装
Install dependencies: 显示 npm install 已执行
Run tests: 显示 npm test 已执行，你应该会看到输出 Running tests...

如果所有步骤都成功完成，则说明你的 CI 工作流正在正常工作。

GitHub Actions logs

总结

在这个实验中，你已成功使用 GitHub Actions 创建了一个基本的持续集成（CI）工作流。你学会了如何：

在 .github/workflows 目录下创建一个 .yml 工作流文件。
配置工作流以在 push 事件上触发。
使用 actions/setup-node action 来配置 Node.js 环境。
添加步骤来安装依赖项 (npm install) 和运行测试 (npm test)。
设置一个基本的 Node.js 项目结构来支持该工作流。

这些技能构成了现代 DevOps 实践的基础，使你能够在每次进行更改时，自动验证你的代码。

GitHub Actions 基础构建与测试

介绍