單元 7 · YAML 生態系

7.1 GitHub Actions · workflow

放在 .github/workflows/*.yml，定義 CI/CD。你現在看的這個教學站就是它部署的。三層結構：on（何時觸發）→ jobs（跑什麼）→ steps（每個 job 的步驟）。

name: CI
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

7.2 Docker Compose · compose.yaml

定義多容器服務。<< 合併鍵常用來共用設定（單元 6），ports 是「序列裡的對映」的應用。

services:
  web:
    build: .
    ports:
      - "8080:80"
    environment:
      NODE_ENV: production
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data: {}

注意 ports / volumes 都是序列；environment 是對映；volumes.db-data: {} 是空對映（留 {} 比留空更明確）。

7.3 Kubernetes · manifest

K8s 資源描述也是 YAML。基本結構：apiVersion、kind、metadata、spec。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27

這是單元 4 的「序列裡的對映」深度應用：containers 底下是序列，每個元素是對映，image 要跟 name 對齊。

7.4 Frontmatter · Jekyll / Hugo / Obsidian

Markdown 檔案頂端的 --- 區塊，用 YAML 描述文件屬性。這是「文件分隔符」最日常的用途（單元 2）。

---
title: YAML 筆記
tags:
  - yaml
  - 教學
date: 2026-08-15
draft: false
---

7.5 其他常見工具

7.6 Worked Example：跨領域驗收

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: api
          image: myapi:1.2
          env:
            - name: LOG_LEVEL
              value: info

練習：找一個 GitHub repo 的 .github/workflows/，讀懂它的 on / jobs / steps；再用 compose 的語法為一個服務寫一份含環境變數與 ports 的片段。

延伸閱讀

• 上一篇：單元 6 · 錨點與別名。
• 下一篇：單元 8 · 實作與最佳實踐。
• 術語表：複習全站。

進階真實情境 Worked Example：完整的 GitHub Actions Matrix CI

Matrix 策略是 GitHub Actions 中最複雜的 YAML 結構之一——序列裡包對映、對映裡包序列、flow 與 block 混用：

name: Matrix CI
on:
  push: {branches: [main]}
  pull_request: {branches: [main]}

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        node: [18, 20, 22]
        exclude:
          - {os: macos-latest, node: 18}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: {node-version: "${{ matrix.node }}"}
      - run: npm test

為什麼這樣設計而非替代方案：on 用 flow 對映而非 block 是因為每個 trigger 只有一行參數，flow 佔行數更少。exclude 用 flow 對映 {os:..., node:...} 是因為每個排除規則只有兩個欄位——如果改用 block 寫，反而多出 4 行縮排。GitHub Actions 社群的慣例是「簡單用 flow、複雜用 block」。

深入原理擴充

各生態工具的 YAML 方言差異

大家以為是這樣但其實不是……

診斷式疑難排解表

進階挑戰題

1. 跨工具 YAML 移植：把同一份 Docker Compose compose.yaml 中的 x- 延伸節點改寫成 Ansible inventory 可用的格式。哪些概念可以直接搬？哪些需要重新設計？
2. GitHub Actions 語法分析：寫一份含 matrix、exclude、include 的 GitHub Actions workflow，然後把所有 GitHub expression（${{ }}）替換成實際值，觀察純 YAML 的結構。
3. 版本偵測：在同一份 YAML 中混合使用 YAML 1.1 的特性（yes 布林）與 1.2 的特性（010 字串），然後用不同解析器（PyYAML、ruamel.yaml、Go yaml.v3）解析，比較結果差異。

① 專案級端到端 Worked Example：雙平台 CI/CD 部署專案

一個產品同時用 GitHub Actions（公開 repo CI）與 GitLab CI（私有部署 pipeline）跑兩條管線，共享同一份 Docker Compose——這是「同一份 YAML 面對不同生態方言」的真實場景：

產出檔案樹

dual-ci-app/
├── .github/workflows/
│   └── ci.yml              # GitHub Actions（matrix + 快取）
├── .gitlab-ci.yml          # GitLab CI（stages + include）
├── docker-compose.yml      # 兩邊測試共用
└── Makefile                # 統一指令入口

關鍵檔案內容

name: CI
on:
  push: {branches: [main]}
  pull_request: {branches: [main]}
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        node: [18, 20]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: {node-version: "${{ matrix.node }}"}
      - run: make test

stages: [test, deploy]

include:
  - project: infra/ci-templates
    file: /node-tests.yml

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - make test
  parallel: 2
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:
  stage: deploy
  image: docker:27
  script:
    - docker compose -f docker-compose.yml up -d

$ actionlint .github/workflows/ci.yml && echo "gh OK"
gh OK

$ curl -X POST --header "PRIVATE-TOKEN: $CI_TOKEN" \
    "$GITLAB_URL/api/v4/projects/1/ci/lint" \
    --data-urlencode "content=$(cat .gitlab-ci.yml)"
{"status":"valid","errors":[]}

$ docker compose -f docker-compose.yml config --quiet && echo "compose OK"
compose OK

關鍵洞察：同一個 CI 意圖（測、建、佈署）在兩個平台用不同 YAML 方言描述——語法關鍵字、觸發方式、變數語法全部不同。這就是「YAML 是方言的世界」，一份 YAML 換平台就是翻譯工程。

② 效能/品質/安全深度

品質：方言差異是移植 bug 的最大來源

移植時最容易漏：GitHub 的 env 是「對映」而 GitLab 的 variables 也是對映——但表達式與預設值語法完全不同，直接複製貼上必爆。

效能：CI 解析與快取

大型 monorepo 的 workflow 檔會拖慢每次 CI 的「排程前解析」。GitHub 有 workflow 快取與 paths 過濾；GitLab 有 rules:changes。用這些機制讓無關檔案變更不觸發整條 pipeline——這才是「YAML 效能」在生態系的真正意義。

安全：expression 注入與 secret 洩漏

③ 站際比較對照表

④ 互動式檢核清單

• 能讀懂 GitHub Actions 的 on / jobs / steps 三層結構。
• 能讀懂 GitLab CI 的 stages / script / rules 結構，並說明與 GitHub 的差異。
• 能用 actionlint 驗證 workflow、用 CI Lint API 驗證 .gitlab-ci.yml。
• 能把一份 CI 設定從 GitHub 移植到 GitLab，並列出至少三個語法翻譯點。
• 能避免把 ${{ }} 事件資料插進 run:，防住 expression 注入。
• 能讓 CI 只對「相關檔案變更」觸發（paths / rules:changes），控制解析與執行成本。