Step 1: 创建工作流(Workflow)文件

欢迎来到 “Hello GitHub Actions”课程! 👋

什么是 GitHub Actions?: GitHub Actions 是一种高度灵活的自动化方式，覆盖软件开发的方方面面。包括自动化测试、CI/CD持续部署、自动化代码审查、管理问题和拉取请求，等等。 最棒的是，这些工作流配置以代码的形式保存在您的git仓库中，可以很方便的在团队之间共享和重用。

• 功能介绍页面：GitHub Actions
• 用户文档：GitHub Actions

什么是 工作流(workflow)?: 工作流是一可配置的自动化过程，可以运行一个或多个 job（任务）。它们写在仓库中 .github/workflows 目录下的特定文件里，并根据设定的事件触发。本练习中，我们会使用 pull_request 事件。

• 想了解更多关于 workflow、job 和事件的内容，请看 “Understanding GitHub Actions”
• 如果你想先看看 pull_request 事件的详细信息，请参考 “pull_request”

为了帮你起步，系统已经在你的仓库里运行了一个 Actions 工作流，并为你创建了一个用于操作的分支，名为 welcome-workflow。

⌨️ 实操环节：创建一个工作流文件

1. 打开一个新的浏览器标签页，方便一边操作一边阅读本教程。

2. 先创建一个 Pull Request，这个 PR 将包含你在本阶段中所有的修改。操作如下:

   • 点击 Pull Requests tab
   • 点击 New pull request
   • 将 base 设为 main，compare 设为 welcome-workflow
   • 点击 Create pull request，再点击一次确认创建

3. 回到 Code 页面。

4. 在分支下拉菜单中，切换到 welcome-workflow 分支。

5. 进入 .github/workflows/ 目录，点击 Add file → Create new file。

6. 在 “Name your file” 输入框中填写：welcome.yml

7. 将以下内容添加到 welcome.yml 文件中：

   name: Post welcome comment
   on:
     pull_request:
       types: [opened]
   permissions:
     pull-requests: write
   

8. 点击 Commit changes 进行提交。

9. 输入提交信息，选择 Commit directly to the welcome-workflow branch，然后点击 Commit changes。

10. 等待大约20秒，然后刷新当前课程页面。GitHub Actions 会自动检测并进入下一步。

Step 2: 为你的工作流添加一个 job

干得漂亮! 🎉 你已经创建了一个 Workflow 文件！

我们先来看看 welcome-workflow 分支里 welcome.yml 文件中的内容分别代表什么：

• name: Post welcome comment 声明工作流名字。它会显示在仓库的 Actions 页面中。
• on: pull_request: types: [opened] 定义触发条件。表示只要有人在这个仓库里新建一个 pull request，这个工作流程就会被触发。
• permissions 用来设置该工作流在仓库里的操作权限。
• pull-requests: write 授予此工作流 pull request 的写权限，这用于之后自动发表评论。

接下来我们需要告诉该流程要运行哪些 job。

什么是 job?: job 可以翻译为 "任务"或“作业”。一个 job 可以理解为在同一台 runner（服务器）上执行的一组步骤。

• 一个工作流可以包含多个 job（任务）
• 每个 job 又由若干个按顺序执行的步骤（step）组成
• 步骤之间是互相关联的 你稍后会继续往这个 workflow 里添加步骤。想深入了解 job，可以参考文档 “Jobs”。

这一节里，我们会添加一个名为 build 的 job，并指定它运行在 ubuntu-latest 这个 runner 上 —— 这是速度最快、成本最低的选项。如果你想知道为什么选它，可以看看这篇文章中对 runs-on: ubuntu-latest 的解释：“Understanding the workflow file”。

⌨️ 实操环节: 为你的流程添加一个 job

1. 确认自己处于 welcome-workflow 分支，然后打开 .github/workflows/welcome.yml 文件。

2. 修改文件内容为以下内容：

   name: Post welcome comment
   on:
     pull_request:
       types: [opened]
   permissions:
     pull-requests: write
   jobs:
     build:
       name: Post welcome comment
       runs-on: ubuntu-latest
   

3. 在编辑器右上角点击 Commit changes。

4. 输入提交信息，并直接提交到 welcome-workflow 分支。

5. 等待大约20秒，然后刷新当前课程页面。GitHub Actions 会自动检测并进入下一步。

Step 3: 为工作流添加一个 step

你已经成功添加了一个 job，干得很棒！💃

接下来我们继续完善它, 在 job 中加入一个 step。

什么是 step（步骤）？** 在 workflow 中，一个 job 由多个 step 组成。step 会从上到下按顺序执行**，并且每一步必须成功，下一步才会继续运行。

每个 step 要么运行一段 shell 脚本，要么调用一个可复用的 action（小写的 “action” 指的是一段可复用的代码逻辑）。关于自定义 actions，可以参考文档 “Finding and customizing actions”，但这一步我们不需要 action，而是直接用 shell 脚本。

我们现在要更新 workflow，让它自动在新的 pull request 下发表评论。这里会用到：

• Bash 脚本
• GitHub CLI

⌨️ 实操环节: 添加一个 step 到工作流中

1. 仍在 welcome-workflow 分支下，打开你的 welcome.yml 文件。

2. 将文件内容更新为以下内容：

   name: Post welcome comment
   on:
     pull_request:
       types: [opened]
   permissions:
     pull-requests: write
   jobs:
     build:
       name: Post welcome comment
       runs-on: ubuntu-latest
       steps:
         - run: gh pr comment $PR_URL --body "Welcome to the repository!"
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             PR_URL: ${{ github.event.pull_request.html_url }}
   

   说明： 我们添加的这个步骤使用 GitHub CLI (gh) 在 pull request 创建时发布一条评论。

   • GITHUB_TOKEN：通过 secrets.GITHUB_TOKEN 提供，用来授权 CLI 发表评论。这是 GitHub 在运行 workflow 时自动生成的token。详情可参考 “Automatic token authentication”。
   • PR_URL：通过 ${{ github.event.pull_request.html_url }} 获取当前 pull request 的地址，供脚本使用。

3. 在右上角点击 Commit changes。

4. 输入提交信息并将修改直接提交到当前分支。

5. 等待大约20秒，然后刷新当前课程页面。GitHub Actions 会自动检测并进入下一步。

Step 4: 合并你的 Workflow 文件

现在你已经能够编写并运行一个 Actions 工作流了！✨

接下来要把它合并进 main 分支，让它真正生效。

⌨️ 实操环节：合并你的 workflow 文件

1. 打开你的仓库，点击 Pull requests 标签页。
2. 找到你在第一步创建的那个 pull request，并点击进入。
3. 点击 Merge pull request，然后再点击 Confirm merge 确认合并。
4. （可选）点击 Delete branch 删除 welcome-workflow 分支。
5. 等待大约20秒，然后刷新当前课程页面。GitHub Actions 会自动检测并进入下一步。

Step 5: 触发工作流

现在你的仓库里已经有一个可以正常运行的工作流程了! 😄

接下来，我们来运行它，看看效果。

这个工作流程里的 shell 脚本会在每当有人新建一个 pull request 时自动执行。

如何查看工作流程是否触发？ 当 pull request 被创建后，GitHub 会自动运行对应的 workflow。在 PR 页面中，你可以看到它的执行状态。如果看到 All checks have passed，说明运行成功。

你也可以打开仓库里的 Actions 标签页，查看所有运行中的或已完成的 workflow。在那里还能点开某次运行，查看详情和日志。

⌨️ 实操环节: 触发工作流

1. 创建一个名为 test-workflow 的新分支。
2. 修改任意文件，比如在 README.md 里加一个 emoji，然后直接提交到这个新分支。
3. 打开 Pull requests 标签页，创建一个从 test-workflow 合并到 main 的 pull request。
4. 查看 PR 页面中的检查（checks）区域，观察 workflow 的运行。
5. 注意工作流自动在该 pull request 下添加的评论。
6. 等待大约20秒，然后刷新当前课程页面。GitHub Actions 会自动检测并进入下一步。

完成

恭喜, 你已经完成了整个课程！

来回顾一下你在这个仓库里完成的所有成果：

• 你创建了你的第一个 GitHub Actions workflow文件
• 你知道了 workflow 文件应该放在哪里
• 你为工作流定义了触发事件（event）、任务（job）和步骤（step）
• 你已经具备了用自动化实现各种想法的能力！

接下来可以做什么？

• 想系统进阶？阅读：Learn GitHub Actions
• 想直接用别人写好的 actions？看看这个仓库：awesome-actions
• 想反馈课程体验？欢迎到讨论区留言：Discussion Board
• 想继续学习相关课程？去这里挑一个：更多 GitHub Actions 课程
• 想了解 GitHub 的更多功能？阅读：Get started
• 想找项目参与？去逛逛：GitHub Explore