在 GitHub Actions 中管理和调试工作流

10 分钟

回想一下，你的目标是自动执行代码生成和发布过程，以便每次开发人员向代码库添加更改时更新功能。

若要实现此过程，请了解如何：

标识触发工作流的事件。
使用 GitHub Actions 工作流日志。
保存和访问构建工件。
在审阅后，自动向拉取请求添加标签。

标识触发工作流的事件

了解触发的 GitHub Actions 工作流对于调试、审核和改进 CI/CD 管道至关重要。触发器类型包括推送到分支、创建或更新的拉取请求、计划的作业或手动调度。可以通过检查工作流运行、存储库更改以及相关的 GitHub 问题或拉取请求来标识触发事件。

图表显示 GitHub Actions 中的各种工作流触发器，比如推送、拉取请求、计划任务和手动触发。

什么是工作流触发器？

工作流触发器是导致工作流运行的事件。 GitHub 支持各种类型的触发器，包括：

push 或 pull_request （基于代码更改）
workflow_dispatch （手动触发器）
schedule（cron 作业）
repository_dispatch （外部系统）
问题、讨论和拉取请求事件（例如，issues.opened、pull_request.closed）

标识触发器事件

可以通过多种方式标识工作流触发器事件：

使用 GitHub Actions UI：
1. 在存储库中，选择操作选项卡。
2. 选择工作流运行。
事件类型（例如 push， pull_request或 workflow_dispatch）显示在工作流运行摘要的顶部。
在日志或工作流中使用github.event_name。
- GitHub 在工作流运行期间公开上下文数据。该 github.event_name 变量告诉你哪个事件触发了工作流。
- 可以在调试过程中打印信息：
```
- name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"
```
使用工作流运行详细信息：
- 如果以编程方式检查工作流运行（例如使用 API），则运行对象包括一个 event 指定触发器的属性。
- 可以找到提交记录的安全哈希算法（SHA）、操作者和时间戳，以跟踪导致触发的原因。

从存储库效果推断触发器

你可能无权直接访问工作流运行，但仍希望根据存储库活动推断触发工作流运行的内容：

观察到的行为	触发事件
新提交已推送到 `main`，并且工作流已运行。	`push` 事件
拉取请求已打开或更新。	`pull_request` 事件
贡献者手动运行工作流。	`workflow_dispatch`
工作流每天在特定时间运行。	`schedule` （cron）
工作流在外部服务调用完成后运行。	`repository_dispatch`
将标签或注释添加到问题时，工作流运行。	`issues.*` 事件

通过查看时间戳、拉取请求活动和提交历史记录，通常可以确定是哪个操作导致了工作流的运行。

总结如何识别触发工作流的内容：

在“操作”选项卡上检查工作流运行摘要。
在工作流中打印或记录 github.event_name 以确保其可见。
比较时间戳和存储库活动（提交、拉取请求、问题）来推断触发器。
使用完整 event 上下文进行更深入的调查。

这些做法可帮助你在开发和部署管道中调试、审核和提高工作流可靠性。

通过读取其配置文件了解工作流效果

要通过读取配置文件来了解工作流的影响，应分析存储在.yml中的.github/workflows/文件的结构和内容。

工作流配置文件指定有关工作流的以下信息：

当它运行时（在 on 分区中）。
它执行的操作（在 jobs 和 steps 中）。
它的运行位置（runs-on 分区）。
它运行的原因（其用途，例如测试、部署或 Lint 分析）。
它在特定条件下的行为方式（环境、筛选器、逻辑）。

解释工作流效果

标识触发器。

若要确定启动工作流的操作，请参阅工作流的on部分。

例如：
```
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
```
此示例工作流：
- 将代码推送到主分支时自动运行（push）。
- 创建或更新拉取请求时运行（pull_request）。
- 可由用户手动触发（workflow_dispatch）。
确定工作流作业和步骤。

若要确定工作流的作用，请参阅工作流中的 jobs 和 steps 部分。

例如：
```
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
```
此示例工作流：
- 使用 Linux 虚拟环境（runs-on）。
- 查看存储库的代码 (steps>name)。
- 安装项目依赖项（steps>name）。
- 运行自动测试（steps>name）。
评估工作流的目的和结果。

通过读取配置文件，可以描述工作流的预期结果：

“此工作流是持续集成（CI）管道。它可确保自动测试推送到存储库或通过拉取请求提交的任何新代码。如果测试失败，GitHub 工作流 UI 会显示此结果，以帮助维护代码质量。
确定或设置影响工作流运行方式的可选功能：
- env 设置环境变量。
- if 仅当满足条件时，才添加条件逻辑以运行特定步骤。
- timeout-minutes 或 continue-on-error 设置工作流执行和错误处理。

诊断失败的工作流运行

在存储库中，转到“操作”选项卡。
查找失败的运行（通常由红色 X 指示）。
选择失败的工作流以打开运行概览。
在工作流日志中，查看错误。
1. 在运行摘要中，展开每个作业和步骤，直到找到指示失败的作业和步骤。
2. 选择作业或步骤以查看其日志。
3. 查找:
  - 错误消息
  - 堆栈跟踪
  - 退出代码
例如，失败的测试可能会显示 npm ERR! Test failed 或 exit code 1。
检查工作流配置文件。

使用 .yml 文件来确定：
- 每个步骤都试图做什么？
- 如果有影响执行的环境变量（env）或条件（if）。
- 如果失败是由于缺少依赖项、语法错误或配置错误步骤导致的。
如果步骤失败，请检查以下原因：
- 依赖项是否已在上一步中成功安装？
- 测试文件是否存在并在本地传递？

常见故障方案

下表描述了常见的工作流失败方案：

症状	可能的原因
步骤失败并返回 `command not found`l	缺少依赖项或错误的设置
`npm install` 失败。	文件损坏 `package-lock.json` 或网络问题
测试步骤失败	单元测试问题、缺少配置文件或无效的测试语法
`Permission denied` 出现。	文件权限不正确或机密缺失

确定如何在 GitHub 中访问工作流日志

在存储库中，转到“操作”选项卡。
在工作流列表中，选择相关的工作流。

例如，如果 .yml 文件具有以下代码，列表中会显示标题为 CI 工作流 的链接：
```
name: CI Workflow
```
选择特定的运行。

在显示状态的运行列表中，选择要检查的特定运行的时间戳或提交消息。
展开每个作业和步骤。

运行摘要页面显示在工作流文件中定义的作业，例如构建或测试：
1. 选择作业以展开。
2. 在作业中，展开各个步骤，例如“安装依赖项”或“运行测试”。
查看日志输出。

若要查看完整的日志输出，包括控制台日志、错误消息和调试信息，请选择工作流步骤。可以复制、搜索和下载日志。

下表总结了访问工作流日志所要执行的步骤：

行动	目的
动作选项卡	查看所有工作流记录。
选择工作流名称	按工作流筛选运行。
选择运行	请查看特定任务和步骤的结果。
展开步骤	查看详细日志。
下载日志	下载用于脱机或团队故障排除的日志。

生成的操作日志

工作流运行时，它会生成一个日志，其中包含所发生事件的详细信息以及任何错误或测试失败。

如果发生错误或测试失败，则会在日志中显示红色 X 而不是绿色复选标记。可以检查错误或失败的详细信息来调查发生了什么情况。

GitHub Actions 日志的屏幕截图，其中包含有关失败的测试的详细信息。

处理工件

当工作流生成日志条目以外的内容时，产品称为项目。例如，Node.js 构建产生一个可以部署的 Docker 容器。容器是一个工件，可以通过使用动作/上传工件动作将其上传到存储。稍后可以使用 actions/download-artifact 从存储下载工件。

存储工件会在作业之间保留工件。每个作业都使用 VM 的新实例，因此不能通过在 VM 上保存项目来重复使用该项目。如果需要在其他作业中使用工件，可以在一个作业中将工件上传到存储，并将其下载到另一个作业中。

工件存储

工件存储在 GitHub 的存储空间中。公共存储库的空间是免费的，某些存储空间对于私有存储库是免费的，这具体取决于帐户。 GitHub 可将工件存储 90 天。

在以下工作流代码片段中，actions/upload-artifact@main 操作中有一个 path 属性。此属性的值是存储项目的路径。在此示例中，指定 公共/ 将所有内容上传到目录。如果只想上传单个文件，请使用 公共/mytext.txt等内容。

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

若要下载用于测试的工件，构建必须成功完成并上传工件。在以下代码中，指定测试作业依赖于生成作业。

test:
    needs: build
    runs-on: ubuntu-latest

在以下工作流代码片段中，你将下载该工件。现在，测试作业可以使用产物进行测试。

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

有关在工作流中使用项目的详细信息，请参阅将工作流数据存储为项目。

使用工作流在 GitHub 上自动化代码审查

使用 pull_request_review 在审阅者批准拉取请求时添加 approved 标签。此示例使用预安装在 GitHub 托管的 Ubuntu 运行器上的 GitHub CLI。

创建标签 approved 并在默认分支上将此工作流保存为 .github/workflows/label-approved.yml。使用同一存储库中分支的新拉取请求进行测试，该请求由其他用户批准。您无法批准自己的拉取请求。

name: Label approved pull requests

on:
  pull_request_review:
    types: [submitted]

permissions:
  issues: write
  pull-requests: write

jobs:
  label-approved:
    if: github.event.review.state == 'approved'
    runs-on: ubuntu-latest
    steps:
      - name: Add approved label
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: gh pr edit "$PR_NUMBER" --add-label approved --repo "$GITHUB_REPOSITORY"

条件 if 仅在审批时运行作业。 GH_TOKEN 对 CLI 进行身份验证，并且无需签出即可通过 --repo 识别存储库。在其他用户批准拉取请求后，确认 approved 标签是否显示，并在 Actions 选项卡中检查运行。该标签记录一次批准；它不强制实施评审要求，也不跟踪被撤销的批准。

Note

添加标签 GITHUB_TOKEN 不会触发侦听类型为 labeled 的 pull_request 事件的工作流。若要触发这些工作流，请改为使用GitHub应用安装访问令牌或个人访问令牌添加标签。

反馈

此页面是否有帮助？