如果说 Jenkins 是 CI/CD 界的“瑞士军刀”GitLab CI 是“一体化平台”那么 GitHub Actions 就是“云原生公民”——它天生与 GitHub 仓库融为一体配置简单、生态丰富、免费配额充足。本文从零开始讲解 GitHub Actions 的核心概念Workflow、Event、Job、Step、Action、Runner以及 .github/workflows/*.yml 的完整语法。通过一个完整的示例你将学会如何用 YAML 文件在 20 行代码内搭建一条生产级的 CI 流水线。一、GitHub Actions 核心概念GitHub Actions 是一套内置于 GitHub 的自动化平台它允许你在特定事件如代码推送、PR 创建发生时自动执行构建、测试、部署等任务。六个核心概念二、Workflow 文件结构Workflow 文件使用 YAML 语法存放在仓库的 .github/workflows/ 目录下。一个典型的 Workflow 包含以下顶层元素# 1. 工作流名称可选建议加上name:CI/CD Pipeline# 2. 触发事件必填on:push:branches:[main,develop]pull_request:branches:[main]# 3. 环境变量可选env:NODE_VERSION:20# 4. 作业定义必填jobs:build:runs-on:ubuntu-lateststeps:-name:Checkout codeuses:actions/checkoutv4-name:Run testsrun:npm test三、事件Events何时触发on 字段定义 Workflow 的触发条件。3.1 单事件触发on:push3.2 多事件触发on:[push,pull_request]3.3 带条件的事件on:push:branches:-main-developpaths:-src/**-!docs/**# 排除 docs 目录pull_request:branches:-maintypes:-opened-synchronizeschedule:-cron:0 2 * * *# 每天凌晨 2 点执行workflow_dispatch:# 手动触发需在 GitHub UI 点击按钮3.4 常用事件类型四、作业Jobs与步骤StepsJob 是 Workflow 的核心执行单元。4.1 基本 Job 定义jobs:build:runs-on:ubuntu-latest# 指定 Runner 环境steps:-name:Checkout codeuses:actions/checkoutv4# 使用预置 Action-name:Run buildrun:npm run build# 执行 Shell 命令4.2 Job 依赖关系默认情况下所有 Job 并行执行。通过 needs 关键字可以控制执行顺序jobs:test:runs-on:ubuntu-lateststeps:-run:npm testbuild:runs-on:ubuntu-latestneeds:test# 等 test 成功后执行steps:-run:npm run builddeploy:runs-on:ubuntu-latestneeds:[test,build]# 等 test 和 build 都成功后执行steps:-run:./deploy.sh4.3 矩阵策略Matrix Strategy用一组并行配置同时运行多个 Job适用于多版本测试或多平台构建jobs:test:runs-on:ubuntu-lateststrategy:matrix:node-version:[18,20,22]os:[ubuntu-latest,windows-latest]steps:-uses:actions/checkoutv4-uses:actions/setup-nodev4with:node-version:${{matrix.node-version}}-run:npm test这会生成 3 × 2 6 个并行 Job分别测试不同 Node 版本和操作系统组合。五、Runner执行环境Runner 是运行 Job 的服务器。5.1 GitHub 托管 RunnerGitHub 提供三种托管 Runnerjobs:build:runs-on:ubuntu-latest5.2 自托管 RunnerSelf-hosted Runner当需要特殊硬件、内网访问或合规要求时可以自托管 Runner。注册步骤进入仓库 Settings → Actions → Runners点击“New runner”选择操作系统按照页面提示下载并运行配置脚本在 Workflow 中使用jobs:build:runs-on:self-hosted六、Actions可复用的功能模块Action 是 GitHub Actions 生态的核心。GitHub Marketplace 提供了超过 20,000 个预置 Action。6.1 最常用的官方 Actions6.2 Action 版本锁定最佳实践始终使用语义化版本标签如 v4而非 main 分支。# ✅ 推荐锁定到主要版本-uses:actions/checkoutv4# ⚠️ 不安全使用 main 分支可能引入破坏性变更-uses:actions/checkoutmain# 最安全锁定到具体 commit SHA-uses:actions/checkoutb4ffde65f46336ab88eb53be808477a3936bae116.3 Action 的输入与输出-name:Set up Node.jsid:setup-node# 设置 ID 以便后续引用输出uses:actions/setup-nodev4with:# 输入参数node-version:20cache:npm-name:Print Node versionrun:echo Node version is ${{steps.setup-node.outputs.node-version}}# 引用输出七、上下文Contexts与表达式GitHub Actions 提供了丰富的上下文变量可在 ${{ }} 中引用。7.1 常用上下文7.2 条件执行steps:-name:Deploy to productionif:github.ref refs/heads/mainsuccess()# 仅在 main 分支且前置步骤成功时执行run:./deploy.sh-name:Notify on failureif:failure()# 仅在失败时执行run:./notify-failure.sh八、第一个完整的 CI Workflow下面是一个完整的 GitHub Actions Workflow展示了拉取代码、设置 JDK、构建、测试、上传制品的完整流程# .github/workflows/ci.ymlname:Java CIon:push:branches:[main,develop]pull_request:branches:[main]jobs:build:runs-on:ubuntu-lateststeps:# 1. 拉取代码-name:Checkout codeuses:actions/checkoutv4# 2. 设置 JDK 17-name:Set up JDK 17uses:actions/setup-javav4with:java-version:17distribution:temurincache:maven# 3. 编译并运行测试-name:Build with Mavenrun:mvn clean package# 4. 上传测试报告-name:Upload test reportsif:always()uses:actions/upload-artifactv4with:name:test-reportspath:target/surefire-reports/# 5. 上传 JAR 包供后续 Job 使用-name:Upload JAR artifactuses:actions/upload-artifactv4with:name:application-jarpath:target/*.jar九、小结GitHub Actions 将 CI/CD 流水线定义为代码存放在 .github/workflows/*.yml 中核心组件Event 触发 → Job 执行 → Step 包含命令或 ActionRunner 是执行环境支持 GitHub 托管ubuntu/windows/macos和自托管Action 是可复用的功能模块从 Marketplace 获取与 Jenkins 和 GitLab CI 相比GitHub Actions 的最大优势是与 GitHub 生态的无缝集成和丰富的 Marketplace 生态。