home / skills / tencentblueking / bk-ci / pipeline-variable-management

pipeline-variable-management skill

safe

This skill helps you manage pipeline variables across lifecycle and extend their fields, improving configuration, transfer, and debugging efficiency.

npx playbooks add skill tencentblueking/bk-ci --skill pipeline-variable-management

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

10.3 KB

---
name: pipeline-variable-management
description: 流水线变量管理完整指南，涵盖变量生命周期（创建、初始化、更新、存储、传递、查询）和变量字段扩展（字段定义、类型扩展、作用域、继承）。当用户开发变量功能、处理变量传递、扩展变量字段或调试变量问题时使用。
---

# 流水线变量管理完整指南

## Skill 概述

**Skill 名称**: Pipeline Variable Management  
**适用场景**: 流水线变量的全生命周期管理与字段扩展  
**重要性**: ⭐⭐⭐⭐ (高优先级)  
**文档版本**: 2.0  
**最后更新**: 2025-01

流水线变量是 BK-CI 流水线中的核心功能，支持在流水线编排、构建执行过程中动态传递和管理数据。本 Skill 提供变量管理的两大核心主题：

1. **变量生命周期** - 变量从创建到销毁的完整流程
2. **变量字段扩展** - 如何扩展变量的数据结构

---

## 一、变量管理架构概览

### 1.1 变量的定义与作用

流水线变量是流水线中用于存储和传递数据的核心机制，支持：

- ✅ **配置参数化** - 将流水线配置中的固定值替换为变量
- ✅ **数据传递** - 在不同 Stage/Job/Task 之间传递数据
- ✅ **动态计算** - 运行时动态生成和更新变量值
- ✅ **用户输入** - 手动触发时由用户输入参数值
- ✅ **系统内置** - 提供系统级别的预定义变量

### 1.2 变量的两种核心模型

BK-CI 中流水线变量存在两种数据模型的双向转换：

#### 1. **BuildFormProperty**（后端内部模型）
- **位置**: `common-pipeline/src/main/kotlin/.../BuildFormProperty.kt`
- **用途**: 微服务内部使用，数据库存储格式
- **特点**: 完整的字段定义，包含 Swagger 注解
- **应用**: Process 模块内部处理、数据持久化

#### 2. **Variable**（YAML 模型）
- **位置**: `common-pipeline-yaml/src/main/kotlin/.../yaml/v3/models/Variable.kt`
- **用途**: YAML 流水线定义，对外 API 交互
- **特点**: Jackson 注解，支持 JSON 序列化
- **应用**: PAC 流水线、OpenAPI 接口

#### 3. **转换器（VariableTransfer）**
- **位置**: `common-pipeline-yaml/src/main/kotlin/.../yaml/transfer/VariableTransfer.kt`
- **职责**: 实现 `BuildFormProperty` ↔ `Variable` 的双向转换
- **核心方法**:
  - `transfer(BuildFormProperty): Variable` - 内部模型 → YAML 模型
  - `transfer(Variable): BuildFormProperty` - YAML 模型 → 内部模型

### 1.3 变量的存储与传递

```
┌─────────────────────────────────────────────────────────────────┐
│                       变量存储与传递架构                          │
└─────────────────────────────────────────────────────────────────┘

  ┌──────────────────┐
  │  流水线配置存储   │  BuildFormProperty
  │  (T_PIPELINE_*) │  存储在 Model JSON 中
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │   构建启动       │  读取变量定义
  │  (StartBuild)   │  初始化变量值
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │  运行时变量存储   │  T_PIPELINE_BUILD_VAR
  │  (BuildVar)     │  构建级别的变量实例
  └────────┬─────────┘
           │
           ├─────────────────┬─────────────────┐
           ▼                 ▼                 ▼
  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
  │   Stage 1      │ │   Stage 2      │ │   Stage 3      │
  │  继承 + 新增   │ │  继承 + 更新   │ │  继承 + 输出   │
  └────────────────┘ └────────────────┘ └────────────────┘
```

---

## 二、两大核心主题

### 2.1 变量生命周期管理

**覆盖内容：**
- 🔄 变量创建与初始化
- 📦 变量存储机制
- 🔀 变量传递与继承
- 🔄 变量动态更新
- 🔍 变量查询与调试

**典型场景：**
- 理解变量在构建执行过程中的完整流转
- 开发新的变量初始化逻辑
- 调试变量传递问题
- 实现变量的动态更新功能

**查阅文档**: [reference/1-lifecycle.md](reference/1-lifecycle.md) (1414 行)

### 2.2 变量字段扩展

**覆盖内容：**
- 🆕 新增变量字段
- 🔧 字段类型定义
- 🔄 模型转换处理
- 🎯 前后端字段同步

**典型场景：**
- 为变量添加新的属性字段
- 扩展变量类型
- 处理历史数据兼容性
- 同步前后端字段定义

**查阅文档**: [reference/2-extension.md](reference/2-extension.md) (534 行)

---

## 三、使用指南

### 3.1 场景 1：理解变量生命周期

**问题示例：**
- "变量值是如何从流水线配置传递到构建执行的？"
- "插件如何获取和更新变量值？"
- "变量的作用域是如何控制的？"

**操作：** 查阅 [reference/1-lifecycle.md](reference/1-lifecycle.md)

**内容包含：**
1. 变量生命周期全景图
2. 六个关键阶段详解
3. 变量存储表结构
4. 变量传递机制
5. 调试方法与常见问题

### 3.2 场景 2：扩展变量字段

**问题示例：**
- "如何为变量添加一个新的 `allowModify` 字段？"
- "如何扩展变量的可选值列表？"
- "如何确保新字段在 YAML 和内部模型之间正确转换？"

**操作：** 查阅 [reference/2-extension.md](reference/2-extension.md)

**内容包含：**
1. 变量字段扩展完整路径
2. BuildFormProperty 字段定义
3. Variable (YAML) 字段定义
4. VariableTransfer 转换器实现
5. 前端字段同步
6. 测试与验证

---

## 四、核心类与文件速查

### 4.1 变量定义类

| 类名 | 位置 | 用途 |
|------|------|------|
| `BuildFormProperty` | `common-pipeline/.../BuildFormProperty.kt` | 后端内部变量模型 |
| `Variable` | `common-pipeline-yaml/.../Variable.kt` | YAML 变量模型 |
| `VariableTransfer` | `common-pipeline-yaml/.../VariableTransfer.kt` | 模型转换器 |

### 4.2 变量处理服务

| 类名 | 位置 | 职责 |
|------|------|------|
| `PipelineVariableService` | `process/biz-base/.../PipelineVariableService.kt` | 变量业务逻辑 |
| `BuildVariableService` | `process/biz-base/.../BuildVariableService.kt` | 构建变量管理 |
| `VariableAcrossInfoUtil` | `process/biz-base/.../VariableAcrossInfoUtil.kt` | 跨 Job 变量传递 |

### 4.3 数据库表

| 表名 | 用途 |
|------|------|
| `T_PIPELINE_BUILD_VAR` | 构建级别的变量实例（运行时） |
| `T_PIPELINE_SETTING` | 流水线配置（包含变量定义） |
| `T_PIPELINE_MODEL_TASK` | 插件配置（引用变量） |

---

## 五、开发流程

### 5.1 变量功能开发流程

```
1. 明确需求
   ↓
2. 确定涉及的生命周期阶段
   │  → 查阅 reference/1-lifecycle.md
   ↓
3. 是否需要扩展字段？
   ├─ 是 → 查阅 reference/2-extension.md
   │       执行字段扩展流程
   ↓
4. 实现后端逻辑
   │  → 修改 Service/DAO 层
   ↓
5. 前端同步（如需）
   │  → 更新 Vue 组件
   ↓
6. 测试验证
   │  → 单元测试 + 集成测试
   ↓
7. 文档更新
```

### 5.2 常见开发任务

| 任务 | 参考文档 | 关键类 |
|------|----------|--------|
| 新增变量类型 | 2-extension.md | `BuildFormProperty`, `Variable` |
| 变量初始化逻辑 | 1-lifecycle.md | `BuildVariableService` |
| 跨 Job 传递 | 1-lifecycle.md | `VariableAcrossInfoUtil` |
| 变量权限控制 | 1-lifecycle.md | `PipelineVariableService` |
| 变量表达式解析 | - | `utility-components` Skill (reference/2-expression-parser.md) |

---

## 六、与其他 Skill 的关系

### 6.1 依赖的 Skill

- **`pipeline-model-architecture`** - 理解变量在 Model 中的位置
- **`process-module-architecture`** - 理解变量处理的代码架构
- **`utility-components`** (reference/2-expression-parser.md) - 变量引用的表达式解析

### 6.2 被引用的场景

- **PAC 流水线** → 变量在 YAML 中的定义
- **流水线编排** → 变量的创建和配置
- **构建执行** → 变量的初始化和传递
- **插件开发** → 插件如何读取和更新变量

---

## 七、详细文档导航

| 文档 | 内容 | 行数 | 文件大小 |
|------|------|------|----------|
| [1-lifecycle.md](reference/1-lifecycle.md) | 变量生命周期完整流程 | 1414 | 78.7KB |
| [2-extension.md](reference/2-extension.md) | 变量字段扩展指南 | 534 | 20.2KB |

> **使用建议**: 
> - 初学者：先阅读本文档了解整体架构，再深入 1-lifecycle.md
> - 开发者：根据具体开发任务直接查阅对应的 reference 文档
> - 调试：优先查阅 1-lifecycle.md 中的调试章节

---

## 八、常见问题 FAQ

### Q1: 变量和参数有什么区别？
**A**: 在 BK-CI 中，"变量"和"参数"本质上是同一个概念，都是 `BuildFormProperty`。区别在于使用场景：
- **参数**：流水线启动时用户输入的变量
- **变量**：流水线内部定义和使用的变量

### Q2: 如何实现跨 Stage 传递变量？
**A**: 查阅 [reference/1-lifecycle.md](reference/1-lifecycle.md) 中的"阶段四：跨容器传递"章节，了解 `VariableAcrossInfoUtil` 的使用。

### Q3: 新增字段后前端不显示怎么办？
**A**: 按照 [reference/2-extension.md](reference/2-extension.md) 的"步骤 4：前端字段同步"章节，确保前端 Vue 组件已同步更新。

### Q4: 变量值为空或不正确？
**A**: 查阅 [reference/1-lifecycle.md](reference/1-lifecycle.md) 中的"调试方法"章节，使用日志和数据库排查。

---

## 九、版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 2.0 | 2025-01 | 整合 `pipeline-variable-lifecycle` 和 `pipeline-variable-extension`，采用 reference 结构 |
| 1.x | 2024-12 | 独立的两个 Skill |

Overview

This skill is a complete guide for pipeline variable management covering the full lifecycle and field extension of variables in CI pipelines. It focuses on creation, initialization, updating, storage, passing, querying, and how to extend variable fields, types, scope, and inheritance. It is written for developers implementing or debugging variable functionality in a Kotlin-based CI platform. The guide emphasizes practical steps, core classes, and integration points between YAML and internal models.

How this skill works

The skill explains two core models: the internal BuildFormProperty (database and service model) and the YAML Variable model, plus a VariableTransfer converter that maps between them. It documents how variable definitions are read from pipeline configuration, initialized at build start, stored as build-level instances, and inherited or updated across stages and jobs. It also covers field extension: adding new properties, type definitions, conversion logic, backward compatibility, and frontend synchronization.

When to use it

When implementing variable initialization or runtime update logic for builds.
When adding new fields or types to variable definitions and ensuring model conversions.
When debugging variable passing, scope, or inheritance issues across stages and jobs.
When integrating plugin code that must read or modify pipeline variables.
When migrating YAML definitions to internal models or ensuring compatibility.

Best practices

Use the VariableTransfer converter to keep YAML and internal models synchronized and test both directions.
Treat new fields as optional and implement backward compatibility for historical data.
Add unit and integration tests for lifecycle flows: creation, inheritance, updates, and persistence.
Log variable initialization and transfer events to aid debugging and include DB row checks for T_PIPELINE_BUILD_VAR.
Coordinate frontend updates (Vue) when adding fields and validate JSON serialization behavior.

Example use cases

Add a new allowModify boolean field to variables: define in BuildFormProperty and Variable, update VariableTransfer, add frontend support, and run compatibility tests.
Implement dynamic variable initialization at build start using PipelineVariableService and persist initial instances to T_PIPELINE_BUILD_VAR.
Diagnose missing variable values during execution by tracing start-up initialization, cross-job transfer util (VariableAcrossInfoUtil), and build-level storage.
Extend a variable type to support a value list: update YAML model, converter, and ensure DB schema or serialization handles new structure.

FAQ

What is the difference between a variable and a parameter?

They are the same underlying model (BuildFormProperty); parameters are variables provided at pipeline start by users while variables cover internal definitions and runtime values.

How do I pass variables across stages or jobs?

Follow the lifecycle guidance: variables are initialized at build start, persisted to build-level storage, and cross-job transfer utilities handle inheritance and explicit passing; review VariableAcrossInfoUtil usage.

New field added but frontend doesn't show it—what to check?

Ensure the YAML Variable and BuildFormProperty include the field, update VariableTransfer, then synchronize the frontend Vue components and verify JSON serialization and API responses.