agents24 开源项目 GitHub Actions 模板实战：从测试、构建镜像、K8s 部署到安全与审批门禁的完整 CI/CD 技能指南

本文围绕 agents24 开源 Agent 插件市场（multi-harness agentic plugin marketplace）中 cicd-automation 插件的 github-actions-templates 技能展开。该技能封装了一套"开箱即用"的 GitHub Actions 工作流模板库，覆盖自动化测试、Docker 镜像构建推送、Kubernetes 部署、Matrix 多版本矩阵构建、可复用工作流、安全扫描与生产审批门禁等高频场景。读完本文，你将掌握其四类核心工作流模式的完整 YAML 写法、GitHub Actions 的十条生产级最佳实践，并能把该技能与同插件的 deployment-pipeline-design、secrets-management、gitlab-ci-patterns 组合，为任意技术栈搭建可复制的 CI/CD 流水线。

技能定位：一个可被 Agent 按需加载的 CI/CD 知识包

在 agents24 仓库中，技能（Skill）是遵循 progressive disclosure（渐进式披露）设计的模块化知识包，通常在激活时按需加载以节省上下文。github-actions-templates 技能的定义位于 plugins/cicd-automation/skills/github-actions-templates/SKILL.md，其 YAML frontmatter 给出了明确的激活条件：

name: github-actions-templates
description: Create production-ready GitHub Actions workflows for automated testing,
  building, and deploying applications. Use when setting up CI/CD with GitHub Actions,
  automating development workflows, or creating reusable workflow templates.

即：当需要"用 GitHub Actions 搭建 CI/CD"、"自动化开发工作流"或"创建可复用的工作流模板"时，Agent 应自动加载本技能。

该技能属于 cicd-automation 插件（plugins/cicd-automation/）下的四枚技能之一，该插件同时提供 cloud-architect、deployment-engineer、devops-troubleshooter、kubernetes-architect、terraform-specialist 五名领域 Agent 与 workflow-automate 命令，形成"Agent 决策 + 命令执行 + 技能模板"的完整自动化体系。在仓库文档中，该技能被归入"CI/CD Automation (4 skills)"类别，与 deployment-pipeline-design（管线架构）、gitlab-ci-patterns（GitLab CI 实现）、secrets-management（密钥管理）互为补充。

技能原文定义了五个典型应用场景，均可直接作为 Agent 调用时的判定依据：

• 自动化测试与部署（Automate testing and deployment）
• 构建 Docker 镜像并推送至镜像仓库（Build Docker images and push to registries）
• 部署到 Kubernetes 集群（Deploy to Kubernetes clusters）
• 运行安全扫描（Run security scans）
• 为多环境执行矩阵构建（Implement matrix builds for multiple environments）

模式一：测试工作流（Test Workflow）

最基础也最高频的模式：在 push 与 pull_request 事件上触发单元测试，通过 matrix 策略对 Node.js 18/20 两个 LTS 版本并行测试，并上传覆盖率报告。

name: Test

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

要点拆解：

• 触发范围收敛：branches 限定触发分支，避免 dev/feature 分支上的重复 CI 开销；PR 目标仅限 main，保证主干质量。
• 矩阵版本覆盖：node-version: [18.x, 20.x] 声明了受支持的 Node 运行时矩阵，GitHub 会自动为每个组合生成并行 job。
• cache: "npm" 依赖缓存：actions/setup-node@v4 的原生缓存会按 lockfile 哈希命中 ~/.npm，大幅缩短 npm ci 的安装时间——这正是"使用特定 Action 版本 + 缓存依赖"两条最佳实践的落地。
• npm ci 而非 npm install：npm ci 严格依据 package-lock.json 执行，保证 CI 环境与本地一致的确定性依赖解析，同时也满足可复现构建的要求。
• codecov/codecov-action@v4：上传 lcov.info 覆盖率文件，配合 GitHub 状态检查（status checks）可在 PR 上强制覆盖率门禁。

模式二：构建并推送 Docker 镜像（Build and Push Docker Image）

面向容器交付的核心模式：仅在 push 到 main 或打 v* 标签时构建镜像，借助 GitHub Container Registry（ghcr.io）与最小权限声明完成推送，并使用 docker/metadata-action 自动生成语义化标签。

name: Build and Push

on:
  push:
    branches: [main]
    tags: ["v*"]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

要点拆解：

• 最小权限原则：permissions: contents: read + packages: write，仅授予读取代码与写入制品仓库所需的最小 scope——对应最佳实践第 6 条"设置合适的权限"。由于登录使用的是自动注入的 GITHUB_TOKEN，无需长期有效的个人访问令牌（PAT）。
• 元数据驱动的标签策略：metadata-action 根据事件类型自动推导标签——push 分支产生分支标签、PR 产生 PR 标签、v* tag 产生 type=semver 版本标签（完整版 {{version}} 与主次版本 {{major}}.{{minor}}），避免手工维护标签列表。
• GitHub Actions 缓存（GHA cache）：cache-from: type=gha 与 cache-to: type=gha,mode=max 启用仓库级的构建缓存层，mode=max 缓存所有中间层，显著加速后续构建。需要注意，这一特性与 deployment-pipeline-design 技能 中"Docker layer cache 被意外击穿"的排查方向是同一问题的两面——后者提醒不要把 COPY . . 放在依赖安装之前，否则源码任何改动都会使依赖层缓存失效。
• 前置登录依赖：docker/login-action 需在 build-push 之前完成，github.actor 作为登录用户名、GITHUB_TOKEN 作为密码，两者由 GitHub 注入，开箱即用。

模式三：部署到 Kubernetes（Deploy to Kubernetes）

面向 AWS EKS 的部署模式：在 main 分支 push 后，配置 AWS 凭证、刷新 kubeconfig，执行 kubectl apply，并通过 rollout status 与资源巡检完成部署验证。

name: Deploy to Kubernetes

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-west-2

      - name: Update kubeconfig
        run: |
          aws eks update-kubeconfig --name production-cluster --region us-west-2

      - name: Deploy to Kubernetes
        run: |
          kubectl apply -f k8s/
          kubectl rollout status deployment/my-app -n production
          kubectl get services -n production

      - name: Verify deployment
        run: |
          kubectl get pods -n production
          kubectl describe deployment my-app -n production

要点拆解：

• 凭证安全：AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 一律从仓库/环境的 Secrets 注入，绝不硬编码进 YAML——这正是技能原文"Use secrets for sensitive data"的落地形态；更完备的密钥管理实践（Vault、AWS Secrets Manager、GitHub Secrets、External Secrets Operator）见 secrets-management 技能。
• 声明式部署 + 状态跟踪：kubectl apply -f k8s/ 是声明式入口，真正的可靠性来自 kubectl rollout status——它阻塞 job 直至 Deployment 滚动完成或超时，把部署"结果"前置到 CI 内而非事后人工观察。
• 验证闭环：最后一个 step 的 get pods 与 describe deployment 提供了部署后的运行状态快照，若配合后续 smoke test 即为完整部署验证。
• 可观测性留痕：kubectl get services -n production 之类的只读命令会在 job 日志中留下可直接回查的运行证据。

模式四：多平台矩阵构建（Matrix Build）

跨平台、跨 Python 版本的全矩阵测试模式：在 ubuntu / macos / windows 三种 runner 上，分别对 Python 3.9～3.12 并行执行测试。

name: Matrix Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.9", "3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

要点拆解：

• 多操作系统 x 多版本叉积：3 个 OS × 4 个 Python 版本共生成 12 个并行 job，矩阵语法将"枚举工作"交给 GitHub Actions，常用于捕获跨平台路径分隔符、解释器差异等平台相关缺陷。
• 组合爆炸控制：当矩阵规模过大时可使用 include/exclude 语法裁剪组合（本技能文档未展开，但可参考同插件 workflow-automate 命令 中 strategy.matrix 的工程化用法，其示例在 test 阶段同样使用 exclude 排除特定 OS+版本组合）。
• pytest 作为测试入口：Python 生态默认的测试收集器，返回非零退出码即触发 job 失败，天然适配 CI 语义。

注意：技能原文针对模式一、二、四分别标注了 assets/test-workflow.yml、assets/deploy-workflow.yml、assets/matrix-build.yml 等参考文件。在本仓库当前的目录结构中，plugins/cicd-automation/skills/github-actions-templates/ 下仅包含 SKILL.md 本体，未随技能打包 assets 目录——因此以正文内嵌的完整 YAML 为准，它们本身即可直接复制运行。

十条生产级工作流最佳实践

技能原文总结了十条适用于几乎所有 GitHub Actions 工作流的实践经验，逐条解读如下：

1. 使用具体的 Action 版本（@v4 而非 @latest）：锁定主版本可获取自动兼容补丁（GitHub 对 @v4 这类主版本引用会解析到实际 tag），而 @latest 无法追踪上游破坏性变更，导致构建结果不可复现。
2. 缓存依赖以加速构建（Cache dependencies）：如模式一中 cache: "npm"、模式二中 GHA layer cache，缓存命中可将分钟级构建压缩到秒级。
3. 用 Secrets 存放敏感数据（Use secrets）：令牌、密钥、云凭证一律经 ${{ secrets.* }} 注入，日志自动脱敏。
4. 在 PR 上实施状态检查（Implement status checks）：把测试 job 设为 PR 的 required check，保证合入即通过门禁。
5. 用矩阵构建做多版本测试（Use matrix builds）：模式一与模式四的矩阵语法即是最佳实践，扩大多语言/多运行时覆盖。
6. 设置合适的权限（Set appropriate permissions）：模式二的 permissions 块即最小权限示例，避免默认 token 权限过大带来的供应链风险。
7. 用可复用工作流沉淀公共模式（Use reusable workflows）：见下一节，把重复的测试/构建逻辑收敛为 workflow_call 模板，由仓库间或组织级统一维护。
8. 为生产环境实施审批门禁（Implement approval gates for production）：通过 GitHub Environments 的保护规则（required reviewers）强制人工审批，见后文"带审批的部署"章节。
9. 为失败添加通知步骤（Add notification steps for failures）：典型如 if: failure() / if: always() 条件下推送 Slack/邮件告警。
10. 敏感工作负载使用自托管 Runner（Use self-hosted runners）：涉及内部网络、合规数据或大型缓存时，将 job 指向自托管 runner 而非公共 runner。

可复用工作流（Reusable Workflows）

GitHub Actions 支持通过 workflow_call 把通用流程封装为可被其他工作流 uses: 调用的"函数"，这是团队级标准化的核心机制。技能先给出被复用的模板本体：

# .github/workflows/reusable-test.yml
name: Reusable Test Workflow

on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      NPM_TOKEN:
        required: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
      - run: npm test

再给出调用方的消费方式——调用方通过 uses: ./.github/workflows/reusable-test.yml（仓库内相对路径）或 owner/repo/.github/workflows/reusable-test.yml@ref（跨仓库）引用：

jobs:
  call-test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      node-version: "20.x"
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

要点拆解：

• 类型化的输入契约：inputs.node-version 声明 required: true 且 type: string，调用方不传即校验失败，模板行为可预测。type 支持 boolean/number/string 等。
• 显式传递 Secrets：被调用工作流不能隐式访问调用方的 Secrets，必须像参数一样逐一声明并传入——secrets.NPM_TOKEN 的显式声明正是安全边界的设计。
• 同名组合：模式二（构建镜像）、模式四（矩阵测试）等流程都可抽成此类模板，配合组织级模板仓库，即可实现"配置即标准"。这与 workflow-automate 命令 中把 CI 阶段拆为 quality / test / build / deploy 多个独立 job 的分层思想一致，都是为减少重复与不一致而设计。

安全扫描：把漏洞检测嵌进每次提交

技能给出了将开源漏洞扫描接入 CI 的完整方案——Trivy 扫描文件系统（fs）与镜像，产出 SARIF 报告回传 GitHub Security，再由 Snyk 做依赖层扫描：

name: Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@0.28.0
        with:
          scan-type: "fs"
          scan-ref: "."
          format: "sarif"
          output: "trivy-results.sarif"

      - name: Upload Trivy results to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: "trivy-results.sarif"

      - name: Run Snyk Security Scan
        uses: snyk/actions/node@0.4.0
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

要点拆解：

• scan-type: "fs" + scan-ref: "."：对仓库文件系统做全量扫描，适合在依赖安装后检测代码路径中的已知漏洞与错误配置；若改为 image-ref 则可对已构建镜像扫描（见下文同插件命令的用法）。
• SARIF 结果回传：codeql-action/upload-sarif 把 Trivy 输出上传到 GitHub Security tab 的 Code Scanning 界面，漏洞以 PR 内联告警与安全中心报表两种形态呈现，无需切换工具查看。
• 双层扫描互补：Trivy 覆盖容器/文件系统层漏洞，Snyk（snyk/actions/node@0.4.0）覆盖 npm 依赖与传递依赖的漏洞与许可问题，SNYK_TOKEN 经 Secrets 注入。
• 供应链安全延伸：在 workflow-automate 命令 的更完整示例中，同样的 trivy-action@0.28.0 以 image-ref 形式在镜像构建后执行扫描、并将 SARIF 一并上传；同时用 actions/cache 缓存依赖、npm audit 与 npx license-checker 做依赖漏洞与开源许可合规双重校验，可看作本模式在真实全流水线中的扩展形态。

带审批门禁的生产部署（Deployment with Approvals）

技能最后给出"受保护的生产发布"模式：通过 GitHub Environments 把"环境保护规则 + 人工审批 + 成功通知"串联起来。只有打上 v* tag 才触发，部署进入 production 环境时需通过该环境配置的 required reviewers 审批：

name: Deploy to Production

on:
  push:
    tags: ["v*"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://app.example.com

    steps:
      - uses: actions/checkout@v4

      - name: Deploy application
        run: |
          echo "Deploying to production..."
          # Deployment commands here

      - name: Notify Slack
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
          payload: |
            {
              "text": "Deployment to production completed successfully!"
            }

要点拆解：

• 环境即门禁：environment: name: production 使该 job 与名为 production 的 GitHub Environment 绑定，Settings → Environments → production 下配置的 protection rules（如 required reviewers、等待计时器、部署分支限制）会在 job 启动前强制执行——这是"人工审批门禁"在 GitHub Actions 中的标准实现。
• 只对版本 tag 放行：on: push: tags: ["v*"] 把生产部署限定在显式打 tag 的时刻，与语义化版本发布节奏对齐。
• 按结果条件通知：if: success() 限定仅在部署成功时通知，slackapi/slack-github-action@v1 通过 SLACK_WEBHOOK Secret 投递消息；若要"无论成败都告警"，可改用 if: always() 并透传 job.status（同插件 workflow-automate 命令中的 8398a7/action-slack 示例即为此变体）。
• 常见故障对照：如果配置了审批却"生产 job 永远不启动"，需检查 production 环境的 required reviewers 是否指派了真实存在的用户或团队——缺少指派会导致门禁无人审批而无限等待。这一诊断点在 deployment-pipeline-design 技能 的 Troubleshooting 中有明确记录，说明技能之间并非孤立，而是共享一套可复用的运维心智。

组合使用：将模板技能接入真实仓库与 Agent 工作流

上述模式在本仓库中不是孤立的 YAML 收藏夹，而是嵌入了一整套可在多 harness（Claude Code、Codex、Cursor、OpenCode、Copilot、Antigravity）间消费的 Agent 技能体系。实操时有三条接入路径：

1. 直接复制模板：把上文任意 YAML 落到你的仓库 .github/workflows/ 下，按项目技术栈替换版本号、包管理器命令与部署目标即可，无需额外依赖。
2. 通过 Agent 消费本技能：在支持 Agent Skills 的 harness 中按技能名激活（如 gh skill install <marketplace> github-actions-templates），让 Agent 依据 frontmatter 的 description 自动匹配并产出定制化 workflow；单技能安装无需 clone 整个仓库，任意 Agent 均可直接读取 plugins/*/skills/。
3. 与配套技能联动：把本技能作为"GitHub Actions 实现层"，与同插件其他技能拼装出完整方案——
   • 需要设计多环境提升、灰度/蓝绿发布与回滚时，参照 deployment-pipeline-design 的 stage/gate 设计（其 references 中还沉淀了 GitHub Actions 专用高级 YAML 与数据库迁移回滚策略）；
   • 需要接管 CI 中的密钥时，参照 secrets-management，其中包含 hashicorp/vault-action@v2 从 Vault 拉取密钥注入 GitHub Actions、aws secretsmanager 动态取密并 ::add-mask:: 脱敏、Environment Secrets 按环境隔离等可直接拼入本技能模板的 step；
   • 同团队在 GitLab 上维护代码时，gitlab-ci-patterns 提供等价的 GitLab CI 实现，两者可保持流水线语义对齐。

更宏观地看，本技能的每个工作流模式都可被视作 workflow-automate 命令 中"质量门禁 → 全平台测试 → 多环境构建 → 分环境部署 → 部署后验证"五阶段流水线的单点素材；该命令同时提供了用 Python 遍历 .github/workflows/*.y*ml、解析 on 触发器的 WorkflowAnalyzer 工具，可在动手前盘点项目已有自动化缺口。而 deployment-engineer Agent 与 kubernetes-architect Agent 则在更高层面负责把"模板选择、渐进式发布策略、GitOps 落地"串成完整交付。技能文件本身是唯一事实来源：若需进一步核对语法与版本细节，请始终以 SKILL.md 正文为准。

总结

github-actions-templates 技能把 GitHub Actions 最常见的四类工作流（测试、镜像构建、Kubernetes 部署、矩阵构建）连同安全扫描、可复用工作流、生产审批门禁与十条最佳实践，收敛为一套可复制、可验证、可直接落入 .github/workflows/ 的模板库。配合 agents24 仓库同插件的管线设计、密钥管理与 GitLab CI 技能，团队可以在 GitHub Actions 与 GitLab CI 之间保持一致的流水线语义，用"模板 + Agent 自动匹配"的方式让 CI/CD 的搭建从手写 YAML 提升为标准化工程实践。