📚 课程目录第4章 GitHub Actions入门

第4章：GitHub Actions入门：创建第一个Workflow文件、语法、触发事件

说到CI/CD，GitHub Actions算是当下最方便的工具之一了。它直接集成在你的仓库里，不用单独搭服务器。我第一次用的时候，其实心里有点打鼓——能靠谱吗？结果试了一次就真香了。今天咱们就手把手把它跑通。

4.1 第一个Workflow文件

在仓库根目录下建一个文件夹：.github/workflows/。注意，名字不能写错，少个点都不行。我记得有个同事把.github写成了github，折腾半天没反应。

然后创建一个YAML文件，比如ci.yml。内容长这样：

name: CI Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run a one-line script
        run: echo "Hello, CI!"

把这个文件推上去，Actions页面就会自动触发一次运行。我习惯每次先写个最简单的，确认能跑通了再往上加东西。

小技巧：文件名不重要，但尽量用有意义的名字，比如test.yml、deploy.yml。同一个仓库可以有多个workflow文件，各自独立。

4.2 语法拆解：name、on、jobs

咱们把上面的yaml拆开看，其实就三大块：

关键字	作用	必填吗
`name`	工作流显示名称	可选，不写则用文件名
`on`	定义触发事件	必填
`jobs`	定义一个或多个任务	必填

为什么on是必填的？因为GitHub Actions要等事件发生才知道该不该干活。你想想，没有触发器，工作流就彻底休眠了。我曾经在项目里忘了写on，推了代码发现没跑，排查了一小时才发现……嗯，别学我。

jobs下面每项任务可以设定运行环境（runs-on）、策略（strategy）、依赖关系（needs）等。每个job里的steps是顺序执行的。

4.3 Steps：actions vs run

每个step可以是两种东西：

使用现成的action：uses: actions/checkout@v4 ——这就像从市场里拿现成的组件。
直接运行命令：run: echo "Hello"。——适合简单操作。

  关键点：用uses时注意版本号，比如@v4。我曾经踩过坑，用了@master结果某天master分支被换了，流水线全挂。建议用语义化版本或sha。

一个step里可以同时有name、uses、run，但不能同时用uses和run。语法上严格区分。我习惯给每个step加个name，这样日志里好看，排查也方便。

4.4 触发事件详解

触发事件是流水线的开关。最常用的就这几种：

事件	写法示例	备注
推送代码	`on: push`	可以限定分支、路径
PR 操作	`on: pull_request`	可以监听 opened、synchronize 等
定时任务	`on: schedule: - cron: '0 0 * * *'`	每天凌晨运行
手动触发	`on: workflow_dispatch`	需要点按钮

你可能会问：能不能监听 issue 创建？能，但不太常用。我建议初期只用 push 和 pull_request 就够了，等熟悉了再玩花活。

注意：schedule事件最小间隔是5分钟，而且不保证精确执行。GitHub对免费仓库有资源限制，频繁触发可能会被限流。

4.5 这章的核心逻辑图

下面这张图把整个流程串起来了。从事件出发，到workflow，再到jobs和steps，每一层都很清楚。

4.6 实战：创建一个带测试的workflow

说了这么多，直接上手练一个。假设你的项目是一个Node.js应用，那workflow可以写成：

name: Node.js CI

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

你看，步骤很清晰：拉代码 → 装Node → 装依赖 → 跑测试。我一般把这一步叫“基本盘”，项目迁移时先保证这套能跑过。

个人习惯：在on里我会同时写 push 和 pull_request，这样PR只要一提交自动触发测试，代码质量有保障。但注意，push和PR可能重复触发——如果你推送到同一个PR分支，两个事件都触发。可以加types: [opened, synchronize]来过滤。

4.7 常见坑与建议

缩进必须空格：YAML用空格缩进，不能用Tab。我特地在编辑器里开启了显示空白字符。
secret怎么用？：在仓库Settings → Secrets and variables → Actions 里添加，workflow中用${{ secrets.MY_SECRET }}引用。
环境变量：可以用env关键字在job级或step级定义。
缓存依赖：用actions/cache加速安装，新手可以先跳过。

我曾经犯过的错：在on里写了push: branches: [ '**' ]，结果每个分支推送都触发，包括feature分支上的临时提交。团队里其他成员的频繁推送把Actions跑崩了。建议一开始就限定到main或master，等稳定了再放宽。

好了，这一章咱们已经能把一个最简单的workflow跑起来了，也掌握了触发事件的基本配置。你想想看，从零到有一个自动测试的流水线，其实就这几步。下一件事就是去试试手动触发（workflow_dispatch），或者加个定时任务。你有任何疑问，记得看Actions的日志——那是排查问题最好的老师。