GitHub Actions CI/CD 速查手册Workflow 语法、事件触发与自动化实战Reference 项目指南【免费下载链接】reference⭕ Share quick reference cheat sheet for developers.项目地址: https://gitcode.com/gh_mirrors/re/reference本指南以 Reference 开源仓库中的 GitHub Actions 速查表source/_posts/github-actions.md为骨架系统讲解 GitHub Actions 的 Workflow 文件编写、触发事件、Job/Step 编排、Runner 选择、Secrets 管理、Artifacts 与缓存、矩阵策略、条件表达式及并发控制等核心知识点。读完本文你将能够从零编写一套可在 GitHub 仓库中直接运行的 CI/CD 流水线并理解如何将本仓库这样的 Hexo 静态站点项目构建脚本见 package.json接入 GitHub Actions 实现自动化构建、测试与部署。一、GitHub Actions 是什么GitHub Actions 是 GitHub 官方提供的 CI/CD持续集成 / 持续交付平台它允许开发者在 GitHub 仓库中直接自动化软件工作流——包括构建build、测试test和部署deploy代码。与传统的独立 CI 服务器不同GitHub Actions 深度集成于仓库生态事件如 push、pull_request天然与仓库操作绑定Secrets 存储、Artifacts 下载、运行日志查看等能力也直接内置于仓库的 Web 界面中。在 Reference 项目中GitHub Actions 速查表被归类于 Toolkit 分类面向的典型场景包括每次提交代码后自动运行单元测试与 lint 检查在多种 Node.js 版本、多种操作系统上执行矩阵构建构建产物如静态站点 HTML通过 Artifacts 交付或自动部署。二、快速开始Workflow 文件与第一个工作流GitHub Actions 的工作流Workflow定义在特殊的 YAML 文件中通常存放在仓库的.github/workflows目录下每个仓库可包含多个工作流文件每个文件即一个独立工作流。以下是最小可运行的示例hello-worldname: hello-world on: push jobs: hello-world-job: runs-on: ubuntu-latest steps: - name: Hello World run: echo Hello World!查看工作流运行结果在 GitHub.com 上进入仓库主页在仓库名称下方点击Actions标签在左侧边栏点击要查看的工作流本例即hello-world。此时可以看到每次触发的运行记录、每个 Job 的日志、Artifacts 与部署信息。注意on: push是简写形式等价于on: [push]表示仓库发生任何 push 事件时触发该工作流。三、Workflow 语法逐行解析一个更完整的示例learn-github-actions展示了 Workflow 的核心关键字name: learn-github-actions run-name: ${{ github.actor }} is learning GitHub Actions on: [push] jobs: check-bats-version: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev3 with: node-version: 14 - run: npm install -g bats - run: bats -v逐行语法说明行关键字说明name:设置工作流名称是仓库中用于标识该工作流的标签。run-name:为本次运行设置自定义名称可使用 GitHub 上下文${{ github.actor }}动态引用触发运行的用户名。on:指定触发工作流的事件。本例为仓库的任何push事件。jobs:定义一组将作为工作流一部分执行的 Job每个 Job 在工作流中相互独立运行。check-bats-version:工作流中某个 Job 的标识符本例该 Job 名为check-bats-version。runs-on:指定运行 Job 的机器类型本例为最新版 Ubuntu。steps:包含 Job 内按顺序执行的一系列任务步骤。uses:指定 Step 要引用的 Action。例如actions/checkoutv4用于检出仓库代码actions/setup-nodev3用于搭建 Node.js 环境。with:为 Action 指定附加参数与uses搭配使用以配置 Action 行为。node-version:with下的参数指定setup-nodeAction 要安装的 Node.js 版本本例为 14。值得留意的是uses:使用owner/reporef的格式固定引用 Action 版本如actions/checkoutv4这是 GitHub 官方推荐的稳妥做法——将 Action 锁定在具体的 tag 或 commit SHA 上避免上游变更意外破坏流水线。四、触发事件Events何时运行工作流on:关键字定义工作流的触发事件。以下示例在每次 push 时触发name: Event-trigger-on-push-example on: [push] # event is defined here jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Run a script run: echo This workflow runs on every push to the repository.常见事件触发一览表事件名称触发条件push仓库发生 push 时触发。pull_request拉取请求相关事件触发。pull_request_review拉取请求审查事件触发。pull_request_review_comment拉取请求审查评论触发。pull_request_target用于 fork 仓库的工作流以基础仓库权限运行。fork仓库被 fork 时触发。issue_commentIssue 与 PR 评论触发。issuesIssue 事件触发。label标签事件触发。milestone里程碑事件触发。deployment部署触发。deployment_status部署状态更新触发。public仓库从私有变为公开时触发。repository_dispatch自定义仓库事件触发可配合 REST API 手动调用。schedule按定义的计划cron 语法定时触发。workflow_dispatch允许手动触发工作流。workflow_run另一个工作流完成时触发。create分支或标签被创建时触发。delete分支或标签被删除时触发。page_buildGitHub Pages 构建事件触发。releaseRelease 事件触发。watch有人 Star 仓库时触发。registry_package仓库包Package事件触发。statusGit 提交状态更新时触发。project项目看板事件触发。project_card项目看板卡片事件触发。project_column项目看板列事件触发。member协作者事件触发。gollumWiki 页面更新触发。多个事件可以写成数组例如on: [push, pull_request]而schedule、workflow_dispatch等事件还支持with/inputs等更细粒度的配置可按需查阅对应官方说明。五、Job 与 Step编排你的流水线单 Job 示例name: Single Job on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Run a build script run: script/build多 Job 示例一个工作流中可以定义多个 Job它们默认并行执行、相互独立name: CI Workflow on: [push] jobs: job-1: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Runs job 1 run: echo Running Job 1 job-2: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Runs job 2 run: echo Running Job 2 job-3: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Runs job 3 run: echo Running Job 3StepJob 内的最小执行单元Step 是 Job 内按声明顺序执行的任务序列典型模式是「检出代码 → 配置环境 → 安装依赖 → 运行测试」jobs: build: runs-on: ubuntu-latest steps: # step 1 - name: Check out repository uses: actions/checkoutv2 # step 2 - name: Set up Node.js uses: actions/setup-nodev2 with: node-version: 14 # step 3 - name: Install dependencies run: npm install # step 4 - name: Run tests run: npm test实战延伸将 Reference 仓库接入 CI以本仓库Reference一个基于 Hexo 的静态文档站点为例其构建与质量检查脚本定义在 package.json 中test脚本第 20 行执行run-s lint:check format:check即 ESLint 检查与 Prettier 格式校验build脚本第 9-14 行依次执行hexo clean、postcss样式编译、hexo generate静态页生成以及gulp资源压缩依赖管理使用 pnpm仓库根目录存在 pnpm-lock.yaml。因此一个面向该仓库的 CI 工作流可以写成如下形式name: Reference CI on: [push, pull_request] jobs: check-and-build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm test - run: pnpm build其中--frozen-lockfile保证严格按锁文件安装依赖这正是 CI 中可复现构建的关键。该示例展示了「原文档中的通用语法 仓库真实脚本」如何组合出可运行的流水线。六、RunnerGitHub 托管与自托管Runner 是执行 Job 的运行环境通过runs-on指定。GitHub 托管 RunnerGitHub 提供开箱即用的托管 Runnerubuntu-latest是最常用的默认选择name: Workflow on: [push] jobs: build: runs-on: ubuntu-latest # default runner steps: - uses: actions/checkoutv2 - name: Run a script run: echo Hello, world!自托管 RunnerSelf-Hosted Runner当需要定制硬件、内网环境或专用操作系统时可以注册自托管 Runner并将runs-on指定为self-hostedname: Workflow with Self-Hosted Runner on: [push] jobs: build: runs-on: self-hosted steps: - uses: actions/checkoutv2 - name: Run a script run: echo Hello from self-hosted runner!从速查表的编排方式可以看出runs-on仅影响 Job 运行所在的机器Job 内的 Step 编写方式完全一致因此可以在托管与自托管 Runner 之间平滑迁移。若使用自托管 Runner建议在.github/workflows的 Runner 标签上做好区分例如runs-on: [self-hosted, linux]以便同一仓库中混用不同类型的 Runner。七、环境变量与 Secrets环境变量Environment Variables在 Job 或 Step 级别通过env:定义自定义变量jobs: build: runs-on: ubuntu-latest env: CUSTOM_VARIABLE: Hello, World! # Custom variable defined using env: steps: - name: Check environment variable run: echo Value of CUSTOM_VAR is $CUSTOM_VAR注意上例定义的是CUSTOM_VARIABLE而 echo 引用的是$CUSTOM_VAR二者并不一致——实际运行时环境变量名为CUSTOM_VARIABLE引用时应保持变量名完全一致。Secrets仓库机密Secrets 用于存放 Token、密码等敏感信息它们不会出现在日志中。添加仓库级 Secret 的路径为Repository仓库Settings设置Security安全Secrets and VariablesActionsNew Repository Secret使用 Secrets 的示例工作流name: Workflow with Secrets on: [push] jobs: example_job: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv2 - name: Use a secret run: echo The secret is ${{ secrets.MY_SECRET }}在 Step 中通过${{ secrets.MY_SECRET }}表达式引用。需要注意的是GitHub 会在运行日志中对 Secret 值打码脱敏因此上述示例中 Secret 不会以明文出现在日志里实践中应避免将 Secret 直接 echo 输出而应将其写入环境变量或配置文件供后续命令读取。Secrets 的可见范围从大到小依次为 组织级Organization、仓库级Repository与 环境级Environment可按需选择。八、Artifacts 与依赖缓存Artifacts交付与保存构建产物Artifacts 用于在工作流运行间保存构建产物如编译后的二进制、打包的静态文件。访问方式Repository仓库ActionsWorkflow Run具体运行记录Artifactsjobs: build: runs-on: ubuntu-latest steps: - name: Build project run: make build - name: Upload build artifact uses: actions/upload-artifactv3 # upload Artifacts prebuilt action with: name: my-artifact path: path/to/artifactactions/upload-artifact通过name指定产物名称、path指定要上传的文件或目录。下游 Job 可用actions/download-artifact下载从而实现在不同 Job 之间传递构建结果例如「构建 Job 上传 → 部署 Job 下载」的流水线拆分。缓存依赖加速工作流依赖缓存Dependency Cache用于存储下载好的依赖包或已编译的二进制文件从而跳过重复下载、显著加速后续运行jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Cache dependencies uses: actions/cachev2 # stores downloaded packages or compiled binaries with: path: | path/to/dependencies another/path key: ${{ runner.os }}-deps-${{ hashFiles(**/lockfile) }} # hash of the dependency lock file is generated in the OS - name: Install dependencies run: install-command关键点在于key的构造${{ runner.os }}表示当前 Runner 的操作系统hashFiles(**/lockfile)对依赖锁文件如package-lock.json、pnpm-lock.yaml内容取哈希。当锁文件未变化时缓存命中依赖直接复用锁文件一旦变化哈希随之改变便会重新生成缓存——这正是缓存一致性的核心保障。九、Matrix 矩阵策略一次声明、多环境并行验证Matrix 策略允许在多个「版本 × 操作系统」组合上并行运行同一 Job特别适合验证库的跨版本兼容性jobs: build: runs-on: ubuntu-latest strategy: matrix: node-version: [12.x, 14.x, 16.x] # matrix strategy runs enables you to run jobs across multiple combinations of environments and OSs os: [ubuntu-latest, windows-latest, macOS-latest] steps: - uses: actions/checkoutv2 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-nodev1 with: node-version: ${{ matrix.node-version }} - run: npm install - run: npm test env: CI: true说明strategy.matrix下声明的node-version与os数组会做笛卡尔积组合本例共 3×39 种组合每个组合生成一个并行运行的 Job在 Step 中通过${{ matrix.node-version }}、${{ matrix.os }}等表达式动态引用当前组合的取值注意runs-on中应引用${{ matrix.os }}才能真正跨 OS 运行本例将runs-on固定为ubuntu-latest读者可自行将之改为runs-on: ${{ matrix.os }}以获得完整的矩阵能力如需排除某些组合如 Windows 上不跑某个版本可使用matrix.exclude追加排除规则在run: npm test的 Step 上通过env: CI: true注入环境变量是很多测试框架如 Jest在 CI 环境下切换行为的通用约定。十、条件表达式Conditions按需执行 Stepif:条件表达式控制 Step 是否执行常用的判断来源是github上下文。分支条件jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv2 - name: Run build if: github.ref refs/heads/main # Run build step will only execute if the current branch is main. run: make build上例中github.ref refs/heads/main表示仅当当前分支为main时才执行Run build可用于实现「仅在主干分支发布/构建」的语义。事件触发条件jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv2 - name: Run tests if: github.event_name pull_request # Run tests step is executed only when the workflow is triggered by a pull request event run: npm testgithub.event_name pull_request表示仅当工作流由 pull request 事件触发时才执行测试。条件表达式支持、||、!等逻辑运算也可结合secrets、env、matrix、runner等上下文进行组合判断例如if: matrix.os ubuntu-latest github.event_name push。十一、Workflow 命令与并发控制Workflow Commands在 Step 间传递状态Workflow 命令是运行器Runner提供的特殊语法通过echo ... 文件的方式把状态写入 GitHub 环境文件。最常用的场景是在 Step 间传递环境变量steps: - name: Set environment variable run: echo NAMEvalue $GITHUB_ENV当运行在ubuntu-latest等 Linux 环境时bash 命令可以直接使用。写入$GITHUB_ENV的环境变量对后续所有 Step 生效同理还有$GITHUB_OUTPUTStep 输出供后续 Step 通过steps.id.outputs读取、$GITHUB_PATH追加 PATH等环境文件共同构成 Step 间数据传递的官方通道。Concurrency避免重复运行冲突concurrency字段基于分组控制并发。其经典语义是如果同一分组内有新的运行启动则取消该分组中仍在进行中的旧运行。原速查表中的示例基于github.head_refPR 头分支引用分组jobs: my_job: runs-on: ubuntu-latest concurrency: group: ${{ github.head_ref }} cancel-in-progress: true steps: - name: Run a script run: echo Running script...这样当开发者对同一分支连续 push 时旧版本的工作流会被自动取消只保留最新一次运行既节省了 Runner 资源也避免了「旧构建与最新代码不一致」的误导。concurrency也可以声明在 Job 外层的工作流级别从而控制整个工作流的并发。十二、相关速查表延伸阅读GitHub Actions 的 Workflow 文件本身使用 YAML 语法编写事件、上下文表达式的展开又依赖 GitHub 平台能力可以参考 Reference 仓库中的以下相邻速查表继续深入YAML 速查表掌握on:、jobs:、with:等关键字的 YAML 语法基础缩进、列表、映射、多行字符串是编写正确 Workflow 文件的前提GitHub 快捷键速查表涵盖 GitHub.com 站点的常用键盘快捷键可提升在 Actions 页面、代码与 PR 之间切换的浏览效率本速查表源文件source/_posts/github-actions.md。将以上知识点串联起来即可完成从「事件触发 → Job/Step 编排 → 环境与密钥管理 → 构建产物交付 → 缓存与矩阵加速 → 条件与并发控制」的完整 GitHub Actions 自动化闭环。无论是本仓库这类 Hexo 静态站点还是常规的 Node.js/前端项目都可以基于本文的语法骨架快速搭建自己的 CI/CD 流水线。【免费下载链接】reference⭕ Share quick reference cheat sheet for developers.项目地址: https://gitcode.com/gh_mirrors/re/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
