GitHub Actions

GitHub Actions 是 GitHub 内置的自动化平台，允许你在代码仓库中直接定义并运行自动化流程，无需借助任何外部 CI/CD 工具。

常见的用途包括：代码推送后自动运行测试、合并 PR 后自动部署到服务器、定时执行数据抓取脚本等。

GitHub Actions 对公开仓库完全免费，私有仓库每月有 2,000 分钟的免费额度。

核心概念

在开始编写配置文件之前，需要先理解以下几个核心概念，它们之间的关系如下：

仓库（Repository）
└── Workflow（工作流）          ← 一个 .yml 文件 = 一个 Workflow
    ├── Event（触发事件）        ← 什么情况下启动这个 Workflow，如 push、PR
    └── Job（作业）× N          ← 一个 Workflow 可以包含多个并行或串行的 Job
        ├── Runner（运行器）     ← 执行 Job 的服务器，如 ubuntu-latest
        └── Step（步骤）× N     ← Job 内按顺序执行的一系列操作
            ├── Action          ← 可复用的封装好的操作，如 actions/checkout
            └── Run             ← 直接执行 Shell 命令

创建第一个 Workflow

1、目录结构

所有 Workflow 文件必须存放在仓库根目录的 .github/workflows/ 文件夹下，文件名以 .yml 或 .yaml 结尾，文件名可以自定义：

your-repo/
├── .github/
│   └── workflows/
│       ├── ci.yml          ← 持续集成流程（如运行测试）
│       ├── deploy.yml      ← 部署流程
│       └── scheduled.yml   ← 定时任务
├── src/
├── package.json
└── README.md

一个仓库可以有多个 Workflow 文件，它们相互独立，分别由各自定义的事件触发。

2、最简单的 Workflow

下面是一个最基础的示例：每次向仓库推送代码时，打印一行"Hello, GitHub Actions！"：

YAML 文件对缩进非常敏感，必须使用空格缩进，不能使用 Tab 键。建议使用 VS Code 并安装 YAML 插件，可以实时检测格式错误。

触发事件（on）

on 字段定义哪些事件会触发这个 Workflow。可以是单个事件，也可以是多个事件的组合。

1、常用触发事件

2、指定分支或路径过滤

3、定时触发（schedule）

使用标准的 Cron 表达式定义执行时间，时区为 UTC（北京时间 = UTC+8，需换算）：

4、手动触发（workflow_dispatch）

workflow_dispatch 允许在 GitHub 网页的 Actions 标签页中手动点击按钮启动 Workflow，还可以定义输入参数：

Jobs 与 Steps 详解

1、Job 的基本结构

2、运行环境（runs-on）

GitHub 提供以下免费的托管运行器，可以按需选择：

3、Job 之间的依赖（needs）

默认情况下，多个 Job 并行运行。使用 needs 可以设置 Job 的执行顺序，形成串行依赖关系：

4、条件执行（if）

通过 if 可以控制 Job 或 Step 是否执行，常用于区分分支、判断上一步是否成功等：

环境变量与 Secrets

1、环境变量（env）

环境变量可以在 Workflow 的三个层级定义，作用范围依次缩小：

2、GitHub 内置变量（github 上下文）

GitHub Actions 提供了一组内置的上下文变量，可以在任意位置通过 ${{ }} 语法引用：

3、Secrets（敏感信息管理）

密码、API 密钥、服务器地址等敏感信息不能直接写在 yml 文件中（因为代码是公开的），必须存储在 GitHub 仓库的 Secrets 中。

设置步骤：进入仓库页面 → Settings → Secrets and variables → Actions → 点击 New repository secret，填写名称和值后保存。

常用 Actions 介绍

GitHub 官方及社区提供了大量开箱即用的 Action，通过 uses: action名称@版本 引用，可以避免重复编写常见操作。

1、actions/checkout（拉取代码）

几乎所有 Workflow 的第一步都是拉取仓库代码，使用官方的 actions/checkout：

2、actions/setup-node（配置 Node.js 环境）

3、actions/setup-python（配置 Python 环境）

4、actions/cache（缓存依赖加速构建）

每次 Workflow 运行时都重新下载依赖会很慢。使用 cache Action 可以将依赖缓存起来，下次运行时直接使用缓存，大幅缩短构建时间：

5、actions/upload-artifact / download-artifact（Job 间传递文件）

不同 Job 运行在独立的虚拟机上，文件不能直接共享。通过 artifact（产物）可以将一个 Job 的输出文件传递给另一个 Job：

矩阵构建（Matrix）

矩阵构建允许你用一份 Job 配置同时在多个环境下并行运行，常用于跨版本、跨操作系统的兼容性测试：

实战示例

示例一：Node.js 项目 CI（自动测试）

每次推送代码或创建 PR 时，自动安装依赖、运行代码检查和测试：

示例二：Python 项目 CI

示例三：构建并推送 Docker 镜像

示例四：构建后自动部署到服务器

示例五：定时任务（自动备份数据库）

调试技巧

1、开启 Debug 日志

当 Workflow 运行失败但日志信息不够时，可以开启详细调试模式。方法：进入仓库 Settings → Secrets and variables → Actions，添加以下两个 Secret（值均设为 true）：

• ACTIONS_RUNNER_DEBUG：开启运行器详细日志
• ACTIONS_STEP_DEBUG：开启每个 Step 的详细调试日志

2、打印上下文信息辅助排查

3、本地测试 Workflow（使用 act）

每次推送代码才能测试 Workflow 效率很低。act 是一个开源工具，可以在本地模拟运行 GitHub Actions，大幅提升调试效率：

# 安装 act（需要本地已安装 Docker）
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# 在仓库根目录运行所有 Workflow
act

# 只运行指定事件触发的 Workflow
act push

# 只运行指定的 Job
act -j build

本地测试时，act 会使用 Docker 容器模拟 GitHub 运行环境，但部分 Action（如 actions/cache）在本地模拟时效果可能与真实环境有差异，最终结果以 GitHub 上实际运行为准。

常见问题与注意事项

1、权限问题（Permission denied）

如果 Workflow 需要向仓库推送代码或操作 Issues，需要在配置文件中显式声明权限：

2、避免 Workflow 循环触发

如果 Workflow 会自动向仓库推送代码，可能触发新的 push 事件，导致无限循环。解决方法：在自动提交的 commit message 中加入 [skip ci] 关键字，GitHub 会跳过该次提交的 Workflow 触发：

git commit -m "自动格式化代码 [skip ci]"

3、YAML 特殊字符转义

在 run 字段的 Shell 命令中使用 ${{ }} 表达式时，如果表达式包含冒号（:）等 YAML 特殊字符，需要用引号包裹整个值，或改为先赋值给环境变量再使用：

更多完整文档请参考官方文档：https://docs.github.com/zh/actions