GitHub Action 触发与执行说明

这份文档只讲一件事：你提交代码之后，GitHub 怎么自动跑一个程序。
不绑定某个业务项目。

---

1. 它是什么

GitHub Action 是 GitHub 自带的自动化。

你可以把它理解成：

仓库里的一个闹钟 + 一份说明书

• 闹钟：什么时候开始（触发）
• 说明书：开始之后做哪些步骤（workflow）

平时它不运行。只有触发条件成立，GitHub 才会临时开一台机器，按说明书执行，做完就关。

---

2. 术语：workflow / job / step / action / on

网上常见的说法是：

workflow：一个 .yml 文件对应一个 workflow，也就是一次持续集成。一个仓库可以包含多个 workflow，只要在 .github/workflow 目录下的 .yml 都会被 GitHub 执行。
job：一个 workflow 由一个或多个 job 构成，每个 job 代表一个持续集成任务。
step：每个 job 由多个 step 构成，一步步完成。
action：每个 step 可以依次执行一个或多个命令（action）。
on：workflow 的触发条件，决定这份 workflow 什么时候执行。

这套词可以记，但有几处要改准，不然会和真实行为对不上。

正确层级

仓库
 └── 一个或多个 .yml          = 多份 workflow（多份说明书）
      └── 一份 yml 里 1 个或多个 job   = 这份流程里的几项任务
           └── 一个 job 里多个 step    = 这项任务的步骤
                └── 一个 step 里做一件事
                     ├── uses: 某个 action（别人写好的动作）
                     └── 或 run: 一条自己的命令（比如 java -jar）

对应到文件：

name: 提交后自动运行          # 这份 workflow 的名字

on:                           # 触发条件：什么时候跑这份流程
  push:
    branches: [main]

jobs:                         # 这份 workflow 里有哪些任务
  build:                      # 第 1 个 job
    runs-on: ubuntu-latest
    steps:                    # 这个 job 分几步
      - name: 拉代码
        uses: actions/checkout@v4    # 这一 step 调用一个 Action
      - name: 运行程序
        run: java -jar app.jar       # 这一 step 自己执行命令

每个词是什么

术语	人话	注意
workflow	一份 .yml 说明书	一个文件 = 一份 workflow。它是可重复用的流程定义，不是「一次持续集成」。同一份 yml 每次 push 都可以再跑一遍
job	这份流程里的一项任务	一个 workflow 可以有多个 job。多个 job 默认可以并行，也可以写成先做 A 再做 B
step	一项任务里的某一步	必须按顺序走。上一步失败，后面默认不跑
action	别人写好、拿来复用的动作	用 uses: 调用，例如 actions/checkout@v4。它不等于所有命令。run: java -jar app.jar 是命令，不是 Action
on	这份 workflow 的闹钟	只有事件对上了，这份 yml 才会跑

原句里要改掉的三处

1. 目录名是 .github/workflows（有 s），不是 .github/workflow。写错 GitHub 不认。
2. 不是「目录里的 yml 都会执行」。GitHub 会把它们都识别成 workflow；会不会跑，看各自的 on。push 只命中写了 on: push 的那几份。
3. workflow ≠ 一次持续集成。持续集成（CI）是一种做法：代码进来就自动检查。workflow 是实现这种做法的说明书。一次真正跑起来，叫一次 run（运行记录）。

和「到底执行谁」对上

on 命中
  → GitHub 执行这份 workflow
    → 按 job、再按 step 往下走
      → 某一步 uses 一个 Action（如 checkout）
      → 某一步 run 一条命令（如 java -jar）
        → 这时才执行 JAR

workflow 管流程，Action / run 管这一步具体干什么，JAR 是 run 拉起来的程序。

---

3. 整体流程

你在本地：git add / git commit / git push
        ↓
代码到达 GitHub 仓库
        ↓
GitHub 发现匹配的触发条件（比如 push 到主分支）
        ↓
启动一个 workflow
        ↓
按步骤执行：拉代码 → 装运行环境 → 运行程序
        ↓
结束（成功或失败都会在 Actions 页面看到记录）

关键点：

• 提交代码是触发器
• workflow 是流程说明
• JAR / 脚本 / 命令是被执行的程序
• 没有触发，程序只是仓库里的文件，不会自己跑

---

4. 文件放哪里

约定位置：

你的仓库/
└── .github/
    └── workflows/
        └── xxx.yml

只要这个目录里有 .yml 文件，GitHub 就会把它当成一份可触发的工作流。

一个仓库可以有多份 workflow。
每一份自己写触发条件，互不影响。

---

5. 什么叫触发

on: 这一段就是触发条件。

常见写法：

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

含义：

事件	什么时候触发
push	有人把代码推到指定分支
pull_request	有人向指定分支提 PR

还可以按路径、按标签、手动点按钮触发。
但对「提交代码就干活」来说，最常用的就是 push 和 pull_request。

注意：

• 推到没写进 branches 的分支，这份 workflow 不会跑
• 只在本地 commit、还没 push，GitHub 收不到，也不会跑

---

6. workflow 最少长什么样

name: 提交后自动运行

on:
  push:
    branches:
      - main

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: 拉代码
        uses: actions/checkout@v4

      - name: 准备 Java
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "11"

      - name: 运行程序
        run: java -jar your-app.jar

拆开看：

1. on：什么时候开始
2. jobs：要做的工作
3. runs-on：用什么机器（一般是 GitHub 提供的 Ubuntu）
4. steps：一步一步做什么
5. run：真正执行的命令

java -jar your-app.jar 只是一个例子。
这里也可以改成 python main.py、npm test、mvn package，本质都一样：触发后执行一条命令。

---

7. JAR 在这里扮演什么角色

JAR 是 Java 程序打好的包。

在 Action 里它通常有两种来源：

方式 A：这次构建出来再跑

mvn clean package
java -jar target/your-app.jar

适合程序和业务代码在同一个仓库。

方式 B：仓库里已经有现成的 JAR

java -jar bin/your-app.jar

适合程序已经打包好，提交后只负责执行。

不管哪种，对 GitHub Action 来说都只是：

触发成功 → 执行 java -jar → 程序跑完退出

它不是网站，也不是一直开着的服务。
这次 workflow 结束，这个进程就结束。

---

8. 和 git 提交的关系

很多人会混这三步：

动作	发生在哪	会不会触发 Action
git commit	只在你电脑上	不会
git push	代码被推到 GitHub	会（如果分支匹配）
在 GitHub 网页上提 PR	GitHub 上	会（如果写了 pull_request）

所以更准确的说法是：

不是「一保存代码就跑」，而是「代码到达 GitHub，并且命中触发条件，才跑」。

---

9. 执行时常见要注意的点

8.1 先拉代码

几乎所有 workflow 第一句都是 checkout。
不拉代码，后面的 JAR、源码、配置都找不到。

如果程序要对比「这一次提交和上一次提交」，checkout 时要加深历史，例如：

- uses: actions/checkout@v4
  with:
    fetch-depth: 2

默认只拉最新一次提交，有时会拿不到上一次 commit。

8.2 先准备运行环境

GitHub 的机器是空的。
要跑 Java，就先 setup-java；要跑 Node，就先 setup-node。

8.3 密钥不要写进 yml

密码、Token、API Key 应放到仓库的 Secrets 里，再在 workflow 里引用：

env:
  APP_TOKEN: ${{ secrets.APP_TOKEN }}

yml 是明文进仓库的，写进去等于公开。

8.4 失败会停

某一步命令返回非 0，后面的步骤默认不再继续。
这就是「程序没跑成功，这次 Action 显示红叉」。

---

10. 你在网页上能看到什么

仓库打开 Actions 页，每一次触发都是一条运行记录。

可以看到：

• 是 push 触发的，还是 PR 触发的
• 哪一次 commit
• 每一步日志
• 最终成功还是失败

这份记录和你的业务程序是分开的。
Action 负责「什么时候跑、跑了没有」；JAR 负责「跑的时候具体干什么」。

---

11. 一张对照表

名词	人话
GitHub Action	GitHub 提供的自动执行能力（整套系统也常被人统称 Actions）
workflow	一份 yml 说明书，不是「一次 CI」
trigger / on	什么事件会启动这份说明书
job	这份流程里的一项任务
step	这项任务里的某一步
action	用 uses: 调用的现成动作，和 run: 自己写的命令不是一回事
runner	临时帮你执行命令的机器
run（一次运行）	这份 workflow 被触发后实际跑的那一遍
JAR	被某一步 run 拉起来的 Java 程序
Secrets	不进代码库的密钥

---

12. 最短记忆

提交并推送到 GitHub
    → 命中 workflow 的 on 条件
    → GitHub 开机执行 yml
    → yml 里的命令去运行 JAR
    → 程序干完活退出

触发的是 Action，跑起来的是程序。
没有触发，JAR 只是一个文件。