cnb-pipeline

Files (9)

• SKILL.md
• best-practices.md · references/
• builtin-tasks.md · references/
• diagnose-guide.md · references/
• env-variables.md · references/
• syntax-reference.md · references/
• .gitignore · validator/
• .web-trigger-schema-cache.json · validator/
• validate.js · validator/

SKILL.md (first lines)

# CNB 流水线配置与诊断

> 本文档 URL 中的 `${CNB_WEB_PROTOCOL:-https}` 和 `${CNB_WEB_HOST:-cnb.cool}` 为环境变量，使用前先 `echo` 获取实际值再拼接。

## 模式判定

根据用户意图自动选择工作模式：

- **配置模式**（写/改流水线）→ 走下方「配置工作流程」
- **诊断模式**（失败/报错/慢/优化）→ 走下方「诊断工作流程」

## 配置工作流程

1. **了解需求** -- 明确触发分支、事件、构建语言/环境、构建步骤、特殊需求。信息充足可直接生成。
2. **查看现有配置** -- 修改场景下先读取 `.cnb.yml` 和 `.ci/` 目录。
3. **按需加载文档** -- 遇到不确定的语法细节时，读取本 skill 的 `references/` 子目录下对应参考文件；也可 `echo` 获取环境变量拼接在线文档 URL 用 WebFetch 加载。
4. **生成配置** -- 按下方「结构骨架」生成完整可运行的配置。
5. **校验（必须）** -- 每次生成/修改 `.cnb.yml` 或 `.cnb/web_trigger.yml` 后必须校验通过才能展示给用户。
6. **解释配置** -- 简要说明关键部分。

### 校验命令

> 校验脚本位于本 skill 的 `validator/` 子目录。执行时需用本 skill base directory 的绝对路径（加载 skill 时系统会提示该路径）。

```bash
cd ${SKILL_BASE}/validator && [ -d node_modules ] || npm install
node ${SKILL_BASE}/validator/validate.js <yml-file-path>
```

其中 `${SKILL_BASE}` 替换为本 skill 的 base directory 绝对路径，`<yml-file-path>` 为待校验文件的绝对路径。脚本按文件名自动识别校验类型，无需额外参数：

- `.cnb.yml`（流水线配置）→ `YAML 语法` → `语义校验` → `Schema`，三项均通过才算有效。
- `.cnb/web_trigger.yml`（Web 触发器配置）→ `YAML 语法` → `目录约束`（必须位于 `.cnb/` 下）→ `Schema`，不走 `.cnb.yml` 的语义规则；该文件为可选配置，仓库未配置时校验自动跳过。

`--refresh` 可强制更新 Schema 缓存。

### 校验失败处理

校验不通过时按以下流程修复：

1. **YAML 语法错误** → 检查缩进（必须空格）、引号、特殊字符转义
2. **语义校验错误** → 根据错误信息定位问题，常见修复：
   - `CNB_ 前缀变量` → 检查拼写，参考 `references/env-variables.md` 内置变量列表
   - `内置任务事件限制` → 将任务移至支持的事件下，参考 `references/builtin-tasks.md` 事件支持表
   - `仓库级事件位置` → 将 `issue.*`/`tag_push` 等移至 `$` 兜底分支下
   - `crontab 事件位置` → 将 `crontab` 移至具体分支名下
3. **Schema 校验错误** → 检查字段名拼写、类型、必填项，参考 `references/syntax-reference.md`

修复后重新执行校验命令，直到全部通过。

## 诊断工作流程

> 详细流程见 `references/diagnose-guide.md`，依赖 [cnb-api] skill。

1. **确定构建 sn**（可选）-- 默认不传，CLI 自动解析；需指定时从 `cnb pulls check-status` 对应检查项的 `target_url` 末段取（勿用 `context` 字段）。
2. **获取数据**：
   - 失败诊断：`cnb pulls get-ci-logs`（自动定位失败构建；也可加 `--sn` 指定）
   - 性能优化：通过 `cnb build --help` / `cnb pulls --help` 探索可用命令，获取 Stage 耗时与慢 Stage 日志
3. **分析并输出报告** -- 判定失败类型或耗时瓶颈，给出修复/优化建议。配置相关问题结合 references 分析。
4. **修复后无需轮询** -- 修复 CI 报错并推送代码后，**不要轮询 CI 状态等待结果**。平台会在 CI 失败时自动唤起 NPC，只需在评论中说明修复内容即可结束当前会话。

---

## 结构骨架

配置层级：**分支 → 事件 → Pipeline → Stage → Job**

```yaml
<branch>:                          # main / "feature/*" / "$"(兜底)
  <event>:                         # push / pull_request / tag_push / ...
    - name: <pipeline-name>
      # runner:                    # 可选，默认 8 核 16G；省核时设 1/2/4，高消耗或 OOM 时可调大到 16/32
      #   cpus: 8
      docker:
        image: node:20             # 或 build (Dockerfile) 或 devcontainer
      services:
        - docker                   # Docker-in-Docker
      env:
        KEY: value
      imports:
        - https://cnb.cool/<org>/<secret-repo>/-/blob/main/secrets.yml
      stages:
        - name: step1
          script: echo hello       # 脚本任务
        - name: step2
          type: cnb:trigger        # 内置任务
          options: { ... }
        - name: step3
          image: plugins/docker    # 插件任务
          settings: { ... }
      failStages: [...]            # stages 失败时执行
      endStages: [...]             # prepare 成功后，无论 stages 成功或失败均执行
```

### Stage 执行语义

| 阶段 | 触发条件 | 是否影响流水线状态 | 典型用途 |
|------|---------|------------------|---------|
| `stages` | 正常顺序执行，**任一任务失败则中断**，剩余任务跳过，跳转到 `failStages` | **是** — 失败则流水线失败 | 构建、测试、部署等业务流程 |
| `failStages` | **仅当 `stages` 中有任务失败时**执行 | **是** — 失败仍标记流水线失败 | 发失败通知、回滚、清理资源 |
| `endStages` | 当 `prepare` 阶段成功后，**无论 `stages` 成功或失败都会执行**（在 `stages` 全部完成或 `failStages` 执行完毕后，流水线结束前依次执行） | **否** — `endStages` 失败不影响流水线最终状态（stages 成功则整体成功） | 清理临时文件、归档日志、上报状态 |

> **常见误区 — 成功/失败通知的正确放置**：
> 若需区分成功和失败发送不同消息：
> - **失败通知** → 放 `failStages`
> - **成功通知** → 放 `stages` **最后一个任务**（前面全部成功才会到达这里）
> - **不要**把"仅成功时才发的通知"放 `endStages`，因为 `endStages` 在失败时也会执行，会导致用户同时收到红色和绿色两条通知

> **详细语法**：完整触发事件列表、Pipeline/Stage/Job 全部字段、变量替换规则、include/!reference、数据卷缓存等见 `references/syntax-reference.md`。
> **内置变量**：常用变量速查见下方，完整 82 个变量列表见 `references/env-variables.md`。
> **内置任务**：所有内置任务类型、参数、支持的事件见 `references/builtin-tasks.md`。

### 常用内置变量（速查）

| 变量 | 说明 |
|------|------|
| `CNB_BRANCH` | 分支/Tag 名 |
| `CNB_COMMIT` / `CNB_COMMIT_SHORT` | Commit SHA |
| `CNB_REPO_SLUG` | 仓库路径 |

From wopal-cn/wopal-space-ontology, MIT.

More from wopal-cn/wopal-space-ontology