GitHub Actions 快速入门 · 学习笔记
来源:GitHub 官方文档 Actions 快速入门、了解 GitHub Actions、工作流 目标读者:完全没用过 CI/CD、没写过 YAML 的人 。读完之后你能亲手跑起第一个 Actions 工作流,并且看懂别人的
.yml文件。
目录
- [先搞懂:GitHub Actions 到底在干什么](#先搞懂:GitHub Actions 到底在干什么 "#1-%E5%85%88%E6%90%9E%E6%87%82github-actions-%E5%88%B0%E5%BA%95%E5%9C%A8%E5%B9%B2%E4%BB%80%E4%B9%88")
- [一套心智模型:5 个名词就够了](#一套心智模型:5 个名词就够了 "#2-%E4%B8%80%E5%A5%97%E5%BF%83%E6%99%BA%E6%A8%A1%E5%9E%8B5-%E4%B8%AA%E5%90%8D%E8%AF%8D%E5%B0%B1%E5%A4%9F%E4%BA%86")
- [动手前的准备(3 个条件)](#动手前的准备(3 个条件) "#3-%E5%8A%A8%E6%89%8B%E5%89%8D%E7%9A%84%E5%87%86%E5%A4%873-%E4%B8%AA%E6%9D%A1%E4%BB%B6")
- 第一步:创建你的第一个工作流文件
- [第二步:读懂这份 YAML(逐行讲解)](#第二步:读懂这份 YAML(逐行讲解) "#5-%E7%AC%AC%E4%BA%8C%E6%AD%A5%E8%AF%BB%E6%87%82%E8%BF%99%E4%BB%BD-yaml%E9%80%90%E8%A1%8C%E8%AE%B2%E8%A7%A3")
- 第三步:提交并触发运行
- 第四步:查看运行结果和日志
- 常见坑与排错清单
- [真实开发场景:10 份可直接改的配置](#真实开发场景:10 份可直接改的配置 "#9-%E7%9C%9F%E5%AE%9E%E5%BC%80%E5%8F%91%E5%9C%BA%E6%99%AF10-%E4%BB%BD%E5%8F%AF%E7%9B%B4%E6%8E%A5%E6%94%B9%E7%9A%84%E9%85%8D%E7%BD%AE")
- 进阶路线:接下来学什么
- 附录:速查表与术语表
1. 先搞懂:GitHub Actions 到底在干什么
一句话:
GitHub Actions 是一个"事件驱动的自动化执行平台",代码一有变化,它就帮你自动跑一串命令。
它最常见的用途叫 CI/CD:
- CI(持续集成):每次有人提交代码,自动装依赖、跑测试,防止"改坏了没人发现"。
- CD(持续交付/部署):测试通过后自动打包、发布、部署到服务器。
但它的能力不止于此。只要仓库里发生了"事件",就能触发:
| 你想要的自动化 | 对应的事件 |
|---|---|
| 每次 push 跑测试 + 检查格式 | push |
| 有人提 PR 时自动跑测试、卡住合并 | pull_request |
| 有人新建 Issue 时自动打标签、分配给负责人 | issues |
| 每天凌晨自动跑一次数据抓取 | schedule(cron) |
| 手动点一下按钮就发布 | workflow_dispatch |
关键认知:不需要你买服务器、装环境、写守护进程。 你在仓库里放一个 .yml 文本文件,GitHub 就会在自己的机器上帮你跑------跑完就销毁。
2. 一套心智模型:5 个名词就够了
这是全篇最重要的一节。把这 5 个词的关系记住,后面所有内容都是它的展开。
less
事件 (event) ──触发──▶ 工作流 (workflow)
│
├─▶ 作业 A (job) ──▶ 运行器 (runner: ubuntu-latest)
│ ├─ 步骤 1:执行命令 run: ...
│ ├─ 步骤 2:用别人写好的动作 uses: ...
│ └─ 步骤 3:...
│
└─▶ 作业 B (job) ──▶ 另一个运行器(和 A 并行)
| 名词 | 英文 | 通俗解释 | 在文件里怎么写 |
|---|---|---|---|
| 事件 | event | 触发条件,"什么情况下开始干活" | on: |
| 工作流 | workflow | 一个完整的自动化流程,就是一个 .yml 文件 |
name: |
| 作业 | job | 工作流里的一件"大事",每个作业独占一台机器 | jobs: 下的键 |
| 步骤 | step | 作业里的一小步,要么跑 shell 命令,要么调用现成的动作 | steps: 列表 |
| 运行器 | runner | 真正跑作业的机器(GitHub 免费提供 Ubuntu / Windows / macOS 虚拟机) | runs-on: |
| 动作 | action | 别人写好的可复用模块(相当于 npm 包 / pip 包) | uses: |
三个必须记住的规则:
- 工作流文件必须放在仓库的
.github/workflows/目录下 ,扩展名必须是.yml或.yaml。放错地方 GitHub 根本不会发现它。 - 步骤之间是串行的 (同一台机器上,按顺序执行,能共享文件);作业之间默认并行 ,除非你用
needs:声明依赖。 - 每个作业都是在一台全新的干净虚拟机上运行,跑完即销毁。所以上一个作业生成的文件,下一个作业默认看不到(要共享得用 artifact)。
3. 动手前的准备(3 个条件)
- 会基本用 GitHub:知道什么是仓库(repository)、提交(commit)、分支(branch)、拉取请求(PR)。
- 有一个自己的仓库,并且你有权限往里加文件(自己的仓库,或别人的仓库给你写权限)。
- 仓库的 Actions 功能是开启的 :打开仓库,顶部能看到 Actions 标签页。 如果看不到 Actions 标签,通常是被关掉了。去
Settings → Actions → General打开。
小技巧:不想污染正式项目,就新建一个空仓库专门用来练手,随便怎么折腾。
4. 第一步:创建你的第一个工作流文件
我们要创建的文件路径是:.github/workflows/github-actions-demo.yml
4.1 在网页上创建(推荐新手)
有两种情况,取决于目录是否已存在:
情况 A:仓库里已经有 .github/workflows/ 目录
- 进入该目录。
- 点 Add file → Create new file。
- 文件名填
github-actions-demo.yml。
情况 B:仓库里什么都没有(全新仓库)
-
回到仓库主页,点 Add file → Create new file。
-
文件名一次性输入完整路径:
bash.github/workflows/github-actions-demo.ymlGitHub 会自动帮你创建
.github和workflows这两个目录------斜杠就是建目录的意思,不用手动一层层建。
关于文件名:
- 名字随便起(
demo.yml、ci.yml、test.yaml都行),但扩展名必须是.yml或.yaml。 - YAML 是一种"用缩进表达层级"的配置文件格式,你不需要精通它,注意只用空格缩进、不要用 Tab 就够了。
4.2 把官方示例内容粘进去
把文件内容换成下面这段(这是官方示例,actions/checkout@v6 是当前版本):
yaml
name: GitHub Actions Demo
run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
on: [push]
jobs:
Explore-GitHub-Actions:
runs-on: ubuntu-latest
steps:
- run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
- run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
- name: Check out repository code
uses: actions/checkout@v6
- run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
- run: echo "🖥️ The workflow is now ready to test your code on the runner."
- name: List files in the repository
run: |
ls ${{ github.workspace }}
- run: echo "🍏 This job's status is ${{ job.status }}."
⚠️ 注意 :这段 YAML 里全是
${{ }}表达式,但 GitHub 网页不会自动转义。如果你是从某个网页复制过来,粘进去之后检查一下缩进有没有被破坏(每级缩进 2 个空格),这是新手最常踩的坑。
4.3 使用现成模板(另一种省事方式)
GitHub 会根据你仓库的代码自动推荐模板(比如检测到 Node.js 就推荐 Node 的 CI)。路径:仓库 → Actions 标签页 → 选一个模板 → Configure → 提交。
模板分类:
- CI:持续集成(构建、测试)
- Deployments:部署
- Automation:自动化日常事务
- Code scanning:代码扫描(安全)
- Pages:发布 GitHub Pages
完整模板库:actions/starter-workflows
5. 第二步:读懂这份 YAML(逐行讲解)
别跳过这节------这是从"会复制粘贴"到"会自己写"的分水岭。
5.1 整体骨架
yaml
name: 工作流的名字 # ← 第一层
run-name: 每次运行显示的名字
on: 触发条件
jobs: # ← 第一层,下面是所有作业
作业ID: # ← 缩进 2 空格
runs-on: 用哪台机器
steps: # 步骤列表
- 第一步 # ← 短横线表示"数组里的一项"
- 第二步
5.2 逐行拆解
name: GitHub Actions Demo
工作流的显示名。在仓库的 Actions 左侧栏里看到的就是它。
run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
某一次运行 的显示名。name 是工作流的名字,run-name 是这次具体运行的名字。 ${{ github.actor }} 是个变量,会被替换成"触发这次运行的人的用户名"。所以你会在运行列表里看到 octocat is testing out GitHub Actions 🚀。
on: [push]
触发条件:有人往仓库 push 代码就运行。
-
[push]是数组简写,等价于:yamlon: - push -
更常见的写法是加过滤条件,比如"只在 main 分支被 push 时运行":
yamlon: push: branches: [main] -
多个事件:
yamlon: [push, pull_request]
jobs:
所有作业的容器。下面每一项(缩进 2 空格)就是一个作业。
Explore-GitHub-Actions:
这是作业的 ID (自己起名,字母数字和 - _)。它在界面上的显示名也是这个。
后面解释:ID 用来被
needs:引用。
runs-on: ubuntu-latest
指定运行器 (跑这个作业的虚拟机):最新版 Ubuntu。 可选常用值:ubuntu-latest、windows-latest、macos-latest。 (-latest 会随 GitHub 升级;想固定就写具体版本号如 ubuntu-22.04。)
steps:
步骤列表 。下面每行以 - 开头,代表一个步骤。同一作业内的步骤按顺序执行。
5.3 两种步骤:run 和 uses
这是 Actions 里最重要的一个区分:
| 写法 | 含义 | 举例 |
|---|---|---|
run: |
直接执行 shell 命令 | run: npm test |
uses: |
调用一个现成的 Action | uses: actions/checkout@v6 |
对比看示例:
yaml
- run: echo "🎉 ..." # ← 执行命令,没有名字
- name: Check out repository code # ← 有名字,方便在日志里识别
uses: actions/checkout@v6 # ← 调用动作
name:是可选的人类友好标签,会显示在日志里。强烈建议给每个步骤加 name,出问题时一眼定位。- run:和- name:里的短横线属于同一个步骤 ,所以name和uses/run要对齐成同样的缩进。
5.4 多行命令和 |
yaml
- name: List files in the repository
run: |
ls ${{ github.workspace }}
run: | 表示"下面是多行 shell 脚本,原样执行"。可以写多行:
yaml
- name: 多步操作
run: |
echo "第一步"
npm ci
npm run build
5.5 ${{ }} 是什么?
这是 上下文表达式(context),Action 运行时会把变量替换成真实值。示例里用到的几个:
| 表达式 | 含义 | 示例输出 |
|---|---|---|
${{ github.actor }} |
触发者用户名 | octocat |
${{ github.event_name }} |
触发事件名 | push |
${{ runner.os }} |
运行器操作系统 | Linux |
${{ github.ref }} |
完整 Git 引用 | refs/heads/main |
${{ github.repository }} |
仓库全名 | octocat/hello-world |
${{ github.workspace }} |
运行器上的工作目录 | /home/runner/work/... |
${{ job.status }} |
当前作业状态 | success |
5.6 那个 actions/checkout 到底做了什么?
没有它,运行器上是空的! 运行器是一台全新虚拟机,里面没有你的代码。
actions/checkout@v6 的作用就是:把你的仓库代码 clone 到运行器的工作目录。
所以逻辑链是:
- 前 3 步
echo只打印环境信息,不需要代码,能跑通。 checkout把代码拉下来。- 后面的
ls才能列出文件------如果没有 checkout,这里会是一个空目录。 - 真实项目里,
npm ci/pytest/go build这些命令,都必须写在checkout之后。
记住这个顺序:
checkout→setup 环境(node/python...)→安装依赖→构建→测试→部署
@v6 是版本号,别写 @main(不稳定),也别省略(会报错)。
6. 第三步:提交并触发运行
滚动到页面底部,GitHub 会弹出 Commit changes / Propose changes 对话框,有两个选择:
| 选项 | 结果 | 适合场景 |
|---|---|---|
Commit directly to the main branch |
直接提交到默认分支 → 立刻触发一次 push 事件 | 练手、自己的项目 |
| Create a new branch + start a pull request | 新建分支并开 PR | 团队协作、规范的代码评审 |
因为示例里写的是
on: [push],只要你把文件提交到任何一个分支,工作流就已经开始跑了------不需要再去点"运行"按钮。
提交完成后,回到仓库首页,稍等几秒,你会看到顶部出现黄色小圆点(运行中)/ 绿色勾(成功)。
7. 第四步:查看运行结果和日志
路径如下(一步步照着点):
- 打开仓库主页。
- 左侧栏 里找到工作流名字------本例是 GitHub Actions Demo,点它。
- 看到运行列表 ,每一行是一次运行。点开想看的那次------名字会是
你的用户名 is testing out GitHub Actions 🚀(这就是run-name的效果)。 - 进入运行详情页,左侧 Jobs 下点 Explore-GitHub-Actions。
- 右侧显示每一步的日志。点任意步骤可以展开看详细输出。
你会看到什么
- 每步前面有个绿色勾 = 成功;红色叉 = 失败。
- 点开
List files in the repository这一步,能看到ls的输出------因为前面 checkout 过,所以这里能列出你的仓库文件。 - 最后一步会打印
🍏 This job's status is success.
跑失败了怎么看
- 先看哪个步骤变红,点开它,读最后的报错信息。
- 常见原因:YAML 缩进错、
uses的版本号写错、命令环境里没有这个工具、忘了checkout。 - 修好之后重新提交(再 push 一次)即可重跑,也可以在该次运行页面点 Re-run jobs 重跑。
8. 常见坑与排错清单
| 现象 | 原因 | 解决 |
|---|---|---|
| Actions 标签页里什么都看不到 | 文件没放在 .github/workflows/ 下;或扩展名不是 .yml/.yaml |
检查路径和扩展名,注意 .github 前面的点 |
| 工作流不触发 | on: 事件和你的操作不匹配;或 branches: 过滤掉了当前分支 |
先写 on: [push] 验证,再逐步收紧 |
| 报 YAML 语法错误 | 用了 Tab 缩进、缩进层级不齐、冒号后缺空格 | 全部用空格,统一 2 空格缩进;key: value 冒号后要有空格 |
uses 报错找不到 action |
少了 @版本,或拼错仓库名 |
写全 owner/repo@version,如 actions/checkout@v6 |
| 命令找不到文件 / 目录是空的 | 忘了 actions/checkout,或把它放在依赖步骤之后 |
checkout 必须是第一个实质步骤 |
| 第二个作业读不到第一个作业的文件 | 不同作业跑在不同虚拟机上 | 用 actions/upload-artifact / download-artifact 传递 |
| 中文/emoji 显示乱码 | 一般不会,Actions 支持 UTF-8 | 文件保存为 UTF-8 |
| 私有仓库跑不动了 | 免费额度用尽 | 去 Settings → Billing 查看 Actions 使用量 |
9. 真实开发场景:10 份可直接改的配置
这一节是"抄作业区"。每份配置都按 场景 → 完整 YAML → 逐块解释"为什么这么配" → 你需要改哪里 组织。 版本号说明:
@v4@v6这类主版本号是必须写的 (不写会报错,写@main则随时可能挂)。具体数字请以各 Action 的 README 为准,本文数字跑得通即可。
场景 1:Vue/React 纯前端项目 → 自动部署 GitHub Pages
最常见的前端场景 :push 到 main 就自动构建并发布,免费、不用服务器。 关键点 :permissions + concurrency + 两段式 build/deploy。
yaml
name: Deploy to GitHub Pages
on:
push:
branches: [main]
workflow_dispatch: # 支持手动点按钮触发
# GitHub Pages 部署必须的三项权限,缺一个就报 403
permissions:
contents: read
pages: write
id-token: write
# 同一时间只跑一个部署,避免两次 push 抢着发布
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: 拉取代码
uses: actions/checkout@v6
- name: 安装 pnpm
uses: pnpm/action-setup@v4
with:
version: 9
- name: 安装 Node 并启用 pnpm 缓存
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm # 自动缓存 pnpm store,二次构建快很多
- name: 安装依赖
run: pnpm install --frozen-lockfile # 严格按 lockfile,锁版本一致
- name: 构建
run: pnpm build
env:
NODE_ENV: production
- name: 配置 Pages
uses: actions/configure-pages@v5
- name: 上传构建产物
uses: actions/upload-pages-artifact@v3
with:
path: dist # Vite 默认 dist;CRA 改 build
deploy:
needs: build # 必须等 build 成功
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: 发布到 Pages
id: deployment
uses: actions/deploy-pages@v4
为什么这么配
| 配置 | 原因 |
|---|---|
permissions 三项 |
Pages 部署走 OIDC,必须 id-token: write。新手 90% 的 Pages 失败都在这 |
concurrency |
两次 push 可能并发部署,互相覆盖。设成串行更安全 |
cache: pnpm |
不加的话每次都要重新下载全部依赖 |
--frozen-lockfile |
CI 里绝不要让依赖被悄悄升级,否则"本地能跑线上挂" |
| build / deploy 拆两个 job | 部署环境隔离,且 environment 能记录部署历史、支持回滚 |
你需要改的 :path: dist 换成你的产物目录;pnpm 版本号;Node 版本。 仓库还需一步 :Settings → Pages → Source 选 GitHub Actions(不是 branch)。
顺手提示:SPA 部署到 Pages 后刷新 404,是因为没有服务端路由回退。解决办法是在
public/放一个404.html,内容为index.html的副本(或用spa-github-pages技巧)。
场景 2:前端项目 → 部署到 Vercel / Netlify(用 Secrets)
Vercel 自带 Git 集成,但当你要在 CI 里跑测试再部署,或者想控制部署时机,就需要这套。
yaml
name: Deploy to Vercel
on:
push:
branches: [main]
pull_request: # PR 也部署一份预览环境
env:
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- name: 质量门禁(先测再发)
run: |
pnpm lint
pnpm test -- --run
- name: 安装 Vercel CLI
run: pnpm add -g vercel@latest
# PR → preview;main → production
- name: 部署
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
vercel deploy --token=${{ secrets.VERCEL_TOKEN }}
else
vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}
fi
Secrets 怎么加 :仓库 Settings → Secrets and variables → Actions → New repository secret 需要三个:VERCEL_TOKEN(账号设置里生成)、VERCEL_ORG_ID、VERCEL_PROJECT_ID(本地跑 vercel link 后看 .vercel/project.json)。
新手最容易犯的错:把 token 直接写进 yml。
只要 token 进过 git 历史,即使后来删掉也视为已泄露,必须立刻重新生成。真的泄露了 GitHub 还会给你发邮件告警。
Netlify 版本(同样思路,更短):
yaml
- name: Deploy to Netlify
run: npx netlify-cli deploy --prod --dir=dist --site=${{ secrets.NETLIFY_SITE_ID }} --auth=${{ secrets.NETLIFY_AUTH_TOKEN }}
场景 3:Node.js 后端 → CI 跑 lint / test / 多版本矩阵(带数据库)
最经典的 CI。这个场景要解决三个问题:跑测试、测多个 Node 版本、测试需要数据库。
yaml
name: CI
on:
push:
branches: [main, develop]
pull_request:
# 同一分支的新提交会取消上一次未跑完的 CI,省额度
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: ubuntu-latest
# 矩阵:一次定义,跑 3 份,互不干扰
strategy:
fail-fast: false # 一个版本挂了不要取消其他版本,方便一次看全
matrix:
node-version: [18, 20, 22]
# 服务容器:GitHub 帮你起一个真实的 Postgres
services:
postgres:
image: postgres:16
env:
POSTGRES_PASSWORD: test
POSTGRES_DB: app_test
ports: ['5432:5432']
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
env:
DATABASE_URL: postgres://postgres:test@localhost:5432/app_test
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }} # ← 矩阵变量在这里注入
cache: pnpm
- run: pnpm install --frozen-lockfile
- name: 代码检查
run: pnpm lint
- name: 类型检查
run: pnpm typecheck
- name: 迁移数据库
run: pnpm db:migrate
- name: 单元测试 + 覆盖率
run: pnpm test -- --coverage
- name: 上传覆盖率报告(失败也能上传)
if: always()
uses: actions/upload-artifact@v4
with:
name: coverage-${{ matrix.node-version }}
path: coverage/
retention-days: 7
为什么这么配
| 配置 | 原因 |
|---|---|
services.postgres |
CI 里不能连公司数据库。用容器起一个临时库,localhost:5432 直接连 |
--health-cmd pg_isready |
不加健康检查的话,容器起来了但数据库还没 ready,测试会随机失败(flaky) |
fail-fast: false |
默认 true 会在第一个版本失败时砍掉其余,你就看不到"到底是版本问题还是代码问题" |
if: always() |
测试失败了日志和报告最有价值,默认行为会在失败时跳过后续步骤 |
cancel-in-progress: true |
CI 用它省钱;部署场景要设 false |
concurrency: group: ci-${{ github.ref }} |
保证取消的是同一分支,不会误杀其他分支的 CI |
分支保护 :到 Settings → Branches → Add branch protection rule,勾选 Require status checks to pass ,选中 test。这样 PR 测试挂了就不能合并------这是 CI 真正发挥作用的地方。
场景 4:Monorepo → 只构建改动的包(paths 过滤 + Turborepo)
Monorepo 最大的痛:改一个包,所有包都构建,CI 跑 40 分钟。
yaml
name: CI (Monorepo)
on:
push:
branches: [main]
pull_request:
jobs:
changes:
runs-on: ubuntu-latest
outputs:
web: ${{ steps.filter.outputs.web }}
server: ${{ steps.filter.outputs.server }}
steps:
- uses: actions/checkout@v6
# 用 paths-filter 判断"哪几个子项目变了",结果作为 outputs 传给下游
- uses: dorny/paths-filter@v3
id: filter
with:
filters: |
web:
- 'apps/web/**'
- 'packages/ui/**'
- 'pnpm-lock.yaml'
server:
- 'apps/server/**'
- 'packages/shared/**'
- 'pnpm-lock.yaml'
build-web:
needs: changes
if: needs.changes.outputs.web == 'true' # 没变就整个 job 跳过
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with: { node-version: 20, cache: pnpm }
- run: pnpm install --frozen-lockfile
- run: pnpm turbo run build --filter=web...
build-server:
needs: changes
if: needs.changes.outputs.server == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with: { node-version: 20, cache: pnpm }
- run: pnpm install --frozen-lockfile
- run: pnpm turbo run build --filter=server...
三种"只跑相关任务"的粒度(按成本从低到高):
| 方式 | 写法 | 粒度 | 适用 |
|---|---|---|---|
| 工作流级 | on.push.paths: ['apps/web/**'] |
整个工作流 | 一个工作流只管一个包,最简单 |
| 作业级 | dorny/paths-filter + needs + if |
单个作业 | 本场景,最常用 |
| 任务级 | Turborepo / Nx 内置远端缓存 | 单个任务 | 大型 monorepo,配合 TURBO_TOKEN 远端缓存效果最好 |
补一句 Turborepo 远端缓存的配置(能再省一半时间):
yaml
- run: pnpm turbo run build
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} # 在 Vercel 上开 Turbo 远端缓存后生成
TURBO_TEAM: ${{ vars.TURBO_TEAM }} # vars 用于非敏感配置,secrets 用于密钥
varsvssecrets的区别:vars明文可见、可在日志里打印,适合 team 名、环境名;secrets加密不可读,适合 token。两者都在Settings → Secrets and variables → Actions里配。
场景 5:Docker 构建并推送到 GHCR(GitHub 自带镜像仓库)
后端/全栈的标准发布流程 :打 tag → 构建镜像 → 推到 ghcr.io。
yaml
name: Docker Publish
on:
push:
tags: ['v*.*.*'] # 只有打 tag(如 v1.2.0)才发布
workflow_dispatch:
permissions:
contents: read
packages: write # 推 GHCR 必须
jobs:
build-push:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
# 让 docker 构建支持多架构、以及内联缓存
- uses: docker/setup-buildx-action@v3
- name: 登录 GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }} # 内置 token,不用自己建
# 自动根据 git tag / 分支生成镜像 tag(语义化标签),别手写
- name: 生成镜像标签
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha,prefix=sha-
- name: 构建并推送
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha # 用 GitHub Actions 缓存层,二次构建快 5~10 倍
cache-to: type=gha,mode=max
为什么这么配
| 配置 | 原因 |
|---|---|
secrets.GITHUB_TOKEN |
每个仓库自动生成、自动续期、权限可限,不需要你去建 PAT |
docker/metadata-action |
打 v1.2.0 标签会同时生成 1.2.0、1.2、sha-abc123 等多个 tag,回滚方便 |
cache-from: type=gha |
不配的话每次全量重建镜像,几分钟变几秒的差别 |
packages: write |
少了这行推镜像报 denied |
tags: ['v*.*.*'] |
只在正式版本发布,避免每次 push 都推镜像污染 registry |
私有镜像拉取 :部署服务器要用 docker login ghcr.io -u <user> --password-stdin,密码用 PAT(含 read:packages)。
场景 6:部署到自己的服务器(SSH + rsync)
没有云平台、只有一台 VPS 的常见做法。
yaml
name: Deploy to VPS
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
environment: production # 可配置需要人工审批
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with: { node-version: 20, cache: pnpm }
- run: pnpm install --frozen-lockfile
- run: pnpm build
# 1) 把构建产物传到服务器(增量同步,--delete 保证一致性)
- name: 同步文件
uses: burnett01/rsync-deployments@7.0.1
with:
switches: -avzr --delete
path: dist/
remote_path: /var/www/myapp/
remote_host: ${{ secrets.SSH_HOST }}
remote_user: ${{ secrets.SSH_USER }}
remote_key: ${{ secrets.SSH_PRIVATE_KEY }}
# 2) 在服务器上重启服务
- name: 重启服务
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.SSH_HOST }}
username: ${{ secrets.SSH_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
script: |
cd /var/www/myapp
pm2 restart myapp || pm2 start server.js --name myapp
echo "deployed at $(date)"
SSH 密钥怎么配(新手最卡的一步):
bash
# 本地生成专用密钥(不要用你日常登录的那把)
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ./deploy_key -N ""
# 公钥放到服务器
ssh-copy-id -i ./deploy_key.pub user@your-server
# 私钥内容(含 BEGIN/END 行)整段贴到 Secret: SSH_PRIVATE_KEY
cat ./deploy_key
关键认知:一次性配置好就不要再动它。 这个私钥等于服务器的一部分门钥匙,只给这一个仓库用。
更现代的替代方案:用云厂商的 OIDC(AWS / GCP / Azure),不存长期密钥:
yaml
permissions:
id-token: write
contents: read
steps:
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789:role/github-actions
aws-region: ap-northeast-1
好处:没有任何长期密钥存在 GitHub 里,泄露风险大幅下降。新项目优先选这个。
场景 7:PR 自动化 → 自动打标签 / 评论 / 卡住超大 PR
团队协作里"省人力"的一类配置,通常一个文件管多件事。
yaml
name: PR Automation
on:
pull_request_target: # 注意:不是 pull_request,见下方解释
types: [opened, synchronize]
permissions:
contents: read
pull-requests: write
jobs:
label:
runs-on: ubuntu-latest
steps:
# 按改动文件路径自动打标签
- uses: actions/labeler@v5
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
# 按改动行数打 size/XS ~ size/XL 标签
- uses: pascalgn/size-label-action@v0.5.5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# 首次贡献者自动欢迎 + 加 first-time-contributor 标签
welcome:
runs-on: ubuntu-latest
steps:
- uses: actions/first-interaction@v1
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
pr-message: '感谢你的第一个 PR!维护者会在 2 个工作日内 review 🎉'
配套 .github/labeler.yml:
yaml
frontend:
- changed-files:
- any-glob-to-any-file: ['src/components/**', 'src/views/**']
docs:
- changed-files:
- any-glob-to-any-file: ['docs/**', '**/*.md']
ci:
- changed-files:
- any-glob-to-any-file: ['.github/**']
⚠️
pull_requestvspull_request_target是最容易出安全事故的一处:
pull_request:来自 fork 的 PR 拿不到 secrets,安全但做不了需要密钥的事。pull_request_target:在目标仓库上下文 运行,能拿到 secrets ------ 所以绝对不要在这个工作流里 checkout 并执行 PR 的代码,否则等于把密钥交给陌生人。- 只打标签、发评论这类"不执行 PR 代码"的操作,用
pull_request_target才安全;要跑 PR 的代码,就用pull_request。
场景 8:定时任务 → 每天自动抓数据并提交回仓库
schedule 用 cron,但 GitHub 的 cron 有几个坑。
yaml
name: Daily Data Sync
on:
schedule:
# 每天 01:00 UTC = 北京时间 09:00
- cron: '0 1 * * *'
workflow_dispatch: # 一定要留手动触发口子,方便调试
permissions:
contents: write # 需要写回仓库
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
persist-credentials: true
- uses: actions/setup-node@v4
with: { node-version: 20 }
- name: 抓取数据
run: node scripts/fetch-data.mjs
- name: 有变化才提交
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
if [[ -n "$(git status --porcelain)" ]]; then
git add .
git commit -m "chore: auto sync data $(date -u +%F)"
git push
else
echo "无变化,跳过"
fi
cron 的 4 个坑
| 坑 | 说明 |
|---|---|
| 时区 | GitHub cron 一律 UTC,北京时间要减 8 小时(09:00 北京 = 01:00 UTC) |
| 不是精确时间 | 高峰期可能延迟 10~30 分钟甚至更久。别用 cron 做秒级/分钟级的事 |
| 最短间隔 5 分钟 | */1 * * * * 会被拒绝或静默忽略 |
| 60 天无提交会停用 | 仓库 60 天没活动,定时工作流会被自动禁用,需要手动重新启用(或定期提交一次保持活跃) |
另外:
git push到受保护分支会被拦;需要走 PR 的话,用peter-evans/create-pull-request这个 Action 代替裸git push。
场景 9:打 tag 自动发布(GitHub Release + npm publish)
开源库的标准发布流程。
yaml
name: Release
on:
push:
tags: ['v*.*.*']
permissions:
contents: write # 创建 Release
id-token: write # npm provenance(供应链证明,强烈建议)
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # changelog 生成需要完整历史
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
registry-url: https://registry.npmjs.org
- run: pnpm install --frozen-lockfile
- run: pnpm build
- run: pnpm test -- --run
# 用 tag 与上一个 tag 之间的 commit 自动生成发布说明
- name: 创建 GitHub Release
uses: softprops/action-gh-release@v2
with:
generate_release_notes: true
# --provenance 会生成可验证的来源证明,是 npm 供应链安全的关键
- name: 发布到 npm
run: npm publish --provenance --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
版本号必须与 tag 一致 :v1.2.0 的 tag 必须对应 package.json 里的 "version": "1.2.0",否则 npm 会拒绝(或用 automation token 覆盖)。 推荐加一步校验,避免手滑:
yaml
- name: 校验 tag 与 package.json 版本一致
run: |
PKG=$(node -p "require('./package.json').version")
TAG=${GITHUB_REF_NAME#v}
[ "$PKG" = "$TAG" ] || { echo "❌ tag=$TAG 但 package.json=$PKG"; exit 1; }
场景 10:多个仓库复用同一套 CI(可复用工作流)
公司有 5 个前端项目,CI 逻辑一模一样。别复制 5 份,抽成一个可复用工作流。
① 在公共仓库 .github/workflows/frontend-ci.yml 里定义模板:
yaml
on:
workflow_call: # ← 关键:表示"这个工作流是给别人调用的"
inputs:
node-version:
type: number
default: 20
working-directory:
type: string
default: '.'
run-e2e:
type: boolean
default: false
secrets:
NPM_TOKEN:
required: false
jobs:
ci:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ${{ inputs.working-directory }}
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
with: { version: 9 }
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: pnpm
cache-dependency-path: ${{ inputs.working-directory }}/pnpm-lock.yaml
- run: pnpm install --frozen-lockfile
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- run: pnpm lint && pnpm typecheck && pnpm test -- --run
- if: ${{ inputs.run-e2e }}
run: pnpm test:e2e
② 在各业务仓库里调用(只有 10 行):
yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
call-ci:
uses: my-org/shared-workflows/.github/workflows/frontend-ci.yml@main
with:
node-version: 20
working-directory: apps/web
run-e2e: false
secrets:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
注意两点
- 被调用的工作流必须在公共仓库里、且该仓库可被访问。私有仓库跨仓库调用,需要在公共仓库的 Actions 设置里允许访问。
uses: org/repo/.github/workflows/x.yml@main中的@main生产环境建议改成 具体 commit SHA 或 tag,防止上游改动影响下游。
场景汇总对照表
| 场景 | 触发 | 关键配置 | 难度 |
|---|---|---|---|
| 1 前端 → Pages | push: main |
permissions: pages/id-token + 双 job |
★★ |
| 2 前端 → Vercel | push / pull_request |
secrets + 环境区分 |
★★ |
| 3 后端 CI | push / pull_request |
matrix + services + concurrency |
★★★ |
| 4 Monorepo | pull_request |
paths-filter + needs + if |
★★★★ |
| 5 Docker 镜像 | push: tags |
permissions: packages + cache: gha |
★★★ |
| 6 部署 VPS | push: main |
SSH 密钥 + environment |
★★★ |
| 7 PR 自动化 | pull_request_target |
pull-requests: write + labeler.yml |
★ |
| 8 定时任务 | schedule + UTC |
contents: write + 变更才提交 |
★★ |
| 9 发布 npm | push: tags |
--provenance + generate_release_notes |
★★★ |
| 10 复用工作流 | workflow_call |
inputs / secrets 声明 | ★★★★ |
通用安全加固清单(上生产前过一遍)
-
每个工作流都写
permissions:,只给最小必要权限(默认可能过宽)。 -
敏感信息一律走
secrets,永不写进 yml、永不echo出来。 -
第三方 Action 固定到 commit SHA ,不要用
@main:yamluses: some/action@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v2.3.1理由是 tag 可以被作者改指向,SHA 不能。
-
PR 工作流永远不执行不可信代码(见场景 7 的提示)。
-
生产部署加
environment: production,配人工审批(Settings → Environments)。 -
加
timeout-minutes,防止卡死烧光额度:jobs.<id>.timeout-minutes: 15。 -
优先用 OIDC 代替长期密钥(AWS/GCP/Azure 都已支持)。
10. 进阶路线:接下来学什么
按这个顺序学,坡度最缓:
第一层:把骨架用熟
on:的各种事件与过滤 ------ 触发工作流needs:让作业串起来,形成"构建 → 测试 → 部署"流水线env/secrets管理环境变量和密钥(密钥千万别写死在 yml 里)if:条件执行;strategy: matrix一次跑多个版本组合
第二层:真实项目 5. 构建和测试代码 ------ 最实用的 CI 6. 发布包 7. 部署到第三方平台 8. 缓存依赖加速(actions/cache)、上传测试报告(artifact)
第三层:工程化 9. 复用工作流(workflow_call)和自定义 Action 10. 自托管运行器、大型运行器 11. 权限最小化(permissions:)、第三方 Action 固定 SHA
11. 附录:速查表与术语表
11.1 最小可用工作流模板(直接抄走)
yaml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: 拉取代码
uses: actions/checkout@v6
- name: 安装 Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: 安装依赖
run: npm ci
- name: 跑测试
run: npm test
11.2 常用键速查
| 键 | 作用 |
|-----------------------------|-------------------------------------------|----------|
| name | 工作流名称 |
| run-name | 单次运行显示名 |
| on | 触发事件(可带 branches / paths / cron 过滤) |
| jobs.<id> | 定义一个作业(ID 自定义) |
| jobs.<id>.runs-on | 用哪种运行器 |
| jobs.<id>.needs | 依赖哪些作业先完成 |
| jobs.<id>.if | 满足条件才执行 |
| jobs.<id>.env | 作业级环境变量 |
| jobs.<id>.steps[].name | 步骤显示名 |
| jobs.<id>.steps[].run | 执行 shell 命令(` | ` 支持多行) |
| jobs.<id>.steps[].uses | 调用 Action(格式 owner/repo@version) |
| jobs.<id>.steps[].with | 传给 Action 的参数 |
| jobs.<id>.strategy.matrix | 矩阵:一次跑多组变量 |
| timeout-minutes | 超时保护,防止卡死烧额度 |
11.3 术语表
- CI/CD:持续集成 / 持续交付部署,自动化构建测试发布的实践。
- Workflow(工作流):一个 YAML 定义的自动化流程。
- Event(事件):触发工作流的仓库活动。
- Job(作业):工作流中的一个任务单元,独占一台运行器。
- Step(步骤) :作业中的最小单元,
run命令或uses动作。 - Runner(运行器):执行作业的机器,GitHub 免费提供托管虚拟机,也可自托管。
- Action(动作) :可复用的自动化模块,可从 Marketplace 获取。
- Artifact(产物):作业产生的文件(日志、构建包、测试报告),可在运行间传递与下载。
- Context(上下文) :
${{ }}中可用的变量集合,如github、env、job、secrets、matrix。 - Secret(密钥) :加密存储的敏感变量,运行时通过
${{ secrets.NAME }}引用。
一句话总结
在
.github/workflows/放一个.yml,声明"什么事件触发(on)→ 在哪台机器跑(runs-on)→ 依次做哪些事(steps)",GitHub 就会在每次事件发生时,免费起一台干净虚拟机,把代码拉下来(checkout)、按顺序执行你的命令,并把日志摊给你看。