GitHub Actions 上传构建制品

介绍

在持续集成（CI）流程中，一个 Job 通常会生成一些文件（例如编译后的二进制文件、webpack 打包文件或测试报告），你可能希望保留或与其他 Job 共享这些文件。这些文件被称为 制品（artifacts）。

默认情况下，在工作流运行期间创建的文件会在运行结束后丢失。要持久化它们，你需要将它们“上传”为制品。

在这个实验（Lab）中，你将修改你的 Node.js 工作流，以模拟一个创建了 dist 目录的构建过程，然后使用 actions/upload-artifact Action 来保存该目录。

这个实验基于你在先前实验中创建的仓库。你将使用 github-actions-demo 仓库。

更新工作流以生成构建文件

在这一步中，你将修改工作流文件（workflow file）以模拟一个构建过程。你将添加一个步骤来创建一个 dist 目录和一个虚拟的构建产物（artifact）文件。

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

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

示例输出：

Cloning into 'github-actions-demo'...
remote: Enumerating objects: X, done.
remote: Counting objects: 100% (X/X), done.
remote: Total X (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (X/X), done.

5. 进入克隆下来的仓库目录：

cd ~/project/github-actions-demo

3. 使用 WebIDE 编辑器创建一个新的工作流文件 .github/workflows/upload-artifacts.yml。你可以在左侧的文件浏览器中 project/github-actions-demo/.github/workflows/ 路径下找到该文件。

4. 首先创建基本的工作流结构。添加工作流名称和触发器：

name: Upload Artifacts

on: [push]

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

jobs:
  build:
    runs-on: ubuntu-latest

6. 添加 steps（步骤）部分。首先，添加 checkout 步骤：

steps:
  - uses: actions/checkout@v4

7. 添加 Node.js 设置步骤：

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

8. 添加安装依赖的步骤：

- name: Install dependencies
  run: npm install

9. 添加构建步骤，该步骤创建 dist 目录和其中的一个文件：

- name: Build project
  run: |
    mkdir dist
    echo "This is the build artifact" > dist/build.txt

10. 添加测试步骤：

- name: Run tests
  run: npm test

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

name: Upload Artifacts

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: Build project
        run: |
          mkdir dist
          echo "This is the build artifact" > dist/build.txt
      - name: Run tests
        run: npm test

解释

• mkdir dist: 创建一个名为 dist 的目录。
• echo ... > dist/build.txt: 在 dist 内部创建一个简单的文本文件，以模拟编译后的资源（asset）。

修改完成后，保存文件（Ctrl+S 或 Cmd+S）。

使用 actions/upload-artifact@v4 上传 dist 目录

既然我们已经生成了一些文件，现在需要将它们上传。我们将使用官方的 actions/upload-artifact Action。

1. 在 .github/workflows/upload-artifacts.yml 文件中，在 Job 的末尾添加一个新的步骤 (step)：

- name: Upload build artifact
  uses: actions/upload-artifact@v4
  with:
    name: build-assets
    path: dist

2. 你的完整文件看起来应该与此类似：

name: Upload Artifacts

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: Build project
        run: |
          mkdir dist
          echo "This is the build artifact" > dist/build.txt
      - name: Run tests
        run: npm test
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-assets
          path: dist

解释 (Explanation)

• uses: actions/upload-artifact@v4: 调用 Action 来处理上传。
• name: build-assets: 构建产物在 GitHub UI 中显示的名称。
• path: dist: 要上传的目录（或文件）。

保存文件 (Ctrl+S 或 Cmd+S)。

提交、推送并在 GitHub UI 中验证制品 (artifact)

在这一步，你将提交更改并将其推送到 GitHub。这将触发你刚刚更新的工作流 (workflow)。

1. 确保你位于仓库目录中：

cd ~/project/github-actions-demo

2. 暂存更改：

git add .

3. 提交更改：

git commit -m "Add build step and upload artifacts"

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

git push

关于认证的说明 (Note on Authentication)

当你运行 git push 时，WebIDE 会自动提示你进行认证。请遵循以下详细步骤：

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

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

此认证过程不需要手动配置用户名或个人访问令牌 (Personal Access Token)。

在 GitHub 上验证 (Verify on GitHub)

1. 在网页浏览器中访问你的 GitHub 仓库。
2. 点击 Actions 标签页。
3. 点击最新的工作流运行记录（例如 "Add build step and upload artifacts"）。
4. 向下滚动到摘要页面的底部。你应该会看到一个标题为 Artifacts 的部分。
5. 你应该会看到一个名为 build-assets 的构件 (artifact)。
6. 点击它以下载。它将是一个包含 build.txt 的 zip 文件。

总结

在这个实验中，你学习了如何使用制品（artifacts）来持久化工作流运行产生的数据。你：

1. 创建了一个生成输出文件的 "build" 步骤。
2. 使用了 actions/upload-artifact 来保存 dist 目录。
3. 验证了该制品可以在 GitHub UI 中下载。

制品对于在 Job 之间共享文件（例如，从构建 Job 到部署 Job）或通过上传日志来调试失败至关重要。