Workflow 文件结构

这一课你将能做到

1. 在仓库创建 .github/workflows/ci.yml，用 on 配置 push / pull_request / workflow_dispatch 三种触发器
2. 读懂最小 workflow 的骨架：name、on、permissions、jobs、runs-on、steps 各管什么
3. 在 GitHub Actions 页手动触发一次 run，并对照日志确认 echo 输出

为什么要学

概念课说过「自动工头」；工头的说明书就是 workflow YAML。路径约定死在 .github/workflows/*.yml（或 .yaml）——放错目录等于没装，GitHub 根本不扫描。

触发器写错时，最常见的懵是：「我 push 了为什么没跑？」或「只想手动跑一次，结果每次 push 都在烧分钟数。」这些都不是玄学，是 on 的语义没吃透。

本课把文件骨架钉牢：何时跑、权限多大、里面有哪些 job。Job 并行/串行、step 细节下一课再拆。

先建立图像

仓库根目录
└─ .github/
   └─ workflows/
      ├─ ci.yml          ← 名称随意，扩展名必须是 yml/yaml
      ├─ docker.yml
      └─ …

一个 workflow 文件 ≈
  name: 页面上显示的名字
  on:   何时启动（触发器）
  permissions: 这次 run 的 GITHUB_TOKEN 能做什么
  jobs:
    job-id:
      runs-on: 哪种虚拟机
      steps:   具体命令 / action

人话：workflow 像一份「外卖单」——写清什么时候下单（on）、厨房在哪（runs-on）、做哪几道菜（jobs/steps）。单子本身也进 Git，改单子要 PR。

键	人话	初学必填？
name	Actions 列表里的标题	建议填
on	触发条件	必须
permissions	token 能力上限	强烈建议显式写
jobs	要跑的任务集合	必须
concurrency	同名 run 互斥/取消旧的	进阶可选

跟着做

步骤 1：创建目录与文件

在本地仓库（或 GitHub 网页 Add file）新建：

.github/workflows/ci.yml

注意是 workflows 复数，不是 workflow。若目录不存在就整条路径新建。提交到一个 feature 分支试水——YAML 语法严重错误时，Actions 页会直接出现醒目的解析失败。

步骤 2：粘贴最小可运行示例

写入：

# 在 Actions 列表里显示的名字
name: CI

# 何时启动这份流水线
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  # 允许在网页上点「Run workflow」手动跑
  workflow_dispatch:

# 默认只读代码，符合最小权限
permissions:
  contents: read

jobs:
  hello:
    # GitHub 托管的 Ubuntu 虚拟机
    runs-on: ubuntu-latest
    steps:
      - name: 打个招呼
        run: echo "Hello CodeRoadMap"