CI 工具流水线技能

使用此技能，基于 CI 工具组件目录构建规范的 GitLab CI/CD 流水线。
当目录中已存在对应作业类型的组件时，优先选用目录组件，而非自定义作业。

快速入门

1. 首先阅读项目中的 AGENTS.md 文件，然后检查仓库结构、当前的 .gitlab-ci.yml 以及现有流水线失败情况。
2. 在选择组件前，请先打开在线组件目录：
   • 目录主页：https://ci-tools.xrow.de/
   • 组件索引页：https://ci-tools.xrow.de/Components/
   • 源代码仓库：https://gitlab.com/xrow-public/ci-tools
3. 选取覆盖项目需求的最小组件集合：
   • 基础能力：common、workflow、semantic-release
   • 工程规范（Hygiene）：label、pre-commit、spellcheck、trivy
   • 语言与测试运行器：bash-unit-tests、lint-javascript、lint-json、lint-yaml、lint-markdown、lint-ansible、lint-helm、lint-tofu
   • 构建与打包：container、buildah、helm、helm-docs、package、package-skill、oras-push
   • 文档与站点：docusaurus、publish-sitemap、publish-wiki
   • 交付部署：deploy-helm、deploy-argocd、gitops、app-of-apps
   • 项目流程模型：workflow-trunkbased、workflow-gitflow
4. 推送前请先本地验证：
   • glab ci lint .gitlab-ci.yml
   • 若项目支持，对所引用的模板文件也执行 lint 检查。
   • 对脚本或生成的配置，运行范围最窄的本地测试。

流水线设计原则

• 根级流水线应以组件驱动为主。仅当无现成组件可用，或必须实现项目特定集成时，才编写手工作业。
• 当涉及包注册中心行为或需完整限定主机名（FQDN）语义时，使用 $CI_SERVER_FQDN/xrow-public/ci-tools/@main 形式引入组件；否则请沿用项目现有风格。
• 将组件的 inputs 配置紧邻 include 声明放置，并在相关作业间保持输入参数名称稳定。
• 默认采用持续交付（Continuous Delivery）模式。除非项目本身已有自动生产环境部署，或当前 Issue 明确要求，否则不得启用自动生产部署。
• 确保验证类作业与部署类作业相互独立，使项目可在向镜像仓库、集群或外部系统写入前快速失败。
• 仅当真实存在制品依赖或执行顺序约束时，才使用 needs 和 dependencies。
• 禁止使用 allow_failure: true、when: manual、rules: when: never 或跳过测试等方式掩盖必需流水线的故障。这些机制仅可用于真正可选、已明确文档化、或有意设置门控（gated）的作业。

组件选型启发式规则

仓库初始化

绝大多数仓库应使用以下组件：

include:
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/common@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/label@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/pre-commit@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/trivy@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/workflow@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/semantic-release@main

若项目需通过标准标签（如 priority::*、size::*、type::*、workflow::*）支撑自动化流程，请尽早引入 label 组件。

容器镜像

普通应用镜像请使用 container 组件；若需直接控制镜像构建过程，则选用 buildah 组件。
当仓库存在多个构建根路径时，请显式指定 name 和 path。

include:
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/container@main
    inputs:
      name: app
      path: container/app

Helm Chart

Chart 的构建、测试与发布流程请使用 helm 组件；若需自动生成 Chart 文档，则额外引入 helm-docs。
仅当确实不存在安全的、集群后端支持的测试路径时，才设置 test-enabled: false。

include:
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/helm@main
    inputs:
      name: chart
      path: chart

评审测试（Review Testing）

评审环境应尽可能贴近生产环境，同时将破坏性检查显式化并限制为临时行为。
针对 Helm 评审测试，请通过 Chart values 而非临时 shell 覆盖方式，验证安装、升级、就绪、Ingress、清理及存储等行为。
任何仅用于评审环境的阈值或测试 fixture，均应在 MR 中明确记录，以便评审者理解其与生产默认值的差异原因。

文档

文档站点请使用 docusaurus 组件；若项目对外发布公开页面，则应搭配 publish-sitemap 使用。
请显式传入 name 和 path 参数。

基础设施与 GitOps

请根据仓库类型，选用 lint-ansible、ansible-collection、ansible-ee、ansible-runner、lint-tofu、tofu-module、gitops、deploy-argocd 或 app-of-apps 等组件。
计划（plan）、构建（build）和部署（deploy）阶段应保持分离，除非组件文档中明确说明了更紧密的流程耦合。

验证工作流

1. 编辑前请先获取组件最新页面，并核对输入参数名称：

   curl -fsSL https://ci-tools.xrow.de/Components/ | sed -n '1,220p'
   

2. 校验流水线语法：

   glab ci lint .gitlab-ci.yml
   

3. 对于合并请求（MR），请先跳过 CI 推送，再通过 GitLab Agent 规则手动触发 MR 流水线：

   git push origin  -o ci.skip
   glab ci run --mr
   

4. 若 CI 执行失败，请检查失败作业日志并修复根本问题。若失败源于组件目录或主干分支（main branch），请创建或关联对应依赖 Issue，并将当前 MR 标记为“阻塞”（blocked），而非弱化流水线质量。

评审检查清单

• 流水线在可用前提下，已使用 CI Tools 组件。
• 组件输入参数与在线目录文档保持一致。
• 受保护分支（protected branch）的行为策略已被遵守。
• 必需检查项未被 ci.skip、allow_failure 等机制隐藏。
• 向镜像仓库、集群及部署目标的写入操作，均已受项目既有规则管控。
• Merge Request 描述中列出了实施计划、验收标准及验证命令。