jenkins-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABC Jenkins 发布技能

ABC Jenkins Deployment Skill

交互式触发 Jenkins 构建，支持智能参数推断（自动解析分支名、环境推断）和实时状态监控。

Interactively trigger Jenkins builds, supporting intelligent parameter inference (automatic branch name parsing, environment inference) and real-time status monitoring.

前置条件

Prerequisites

```
JENKINS_USER
```
环境变量已设置（Jenkins 用户名）
```
JENKINS_TOKEN
```
环境变量已设置（Jenkins API Token）
当前在 Git 仓库中（用于自动获取分支和标签）

```
JENKINS_USER
```
environment variable is set (Jenkins username)
```
JENKINS_TOKEN
```
environment variable is set (Jenkins API Token)
Currently in a Git repository (for automatically retrieving branches and tags)

安装

Installation

bash

npx add-skill https://github.com/ABCFed/claude-marketplace/tree/main/skills/jenkins-deploy

bash

npx add-skill https://github.com/ABCFed/claude-marketplace/tree/main/skills/jenkins-deploy

准备

Preparation

bash

undefined

bash

undefined

编辑 ~/.zshrc 或 ~/.bashrc

Edit ~/.zshrc or ~/.bashrc

export JENKINS_USER="your_jenkins_username" export JENKINS_TOKEN="your_jenkins_api_token" source ~/.zshrc

undefined

export JENKINS_USER="your_jenkins_username" export JENKINS_TOKEN="your_jenkins_api_token" source ~/.zshrc

undefined

使用流程

Usage Workflow

方式一：两阶段部署（推荐，进度可见）

Method 1: Two-stage Deployment (Recommended, Progress Visible)

步骤 1：触发构建（返回 JSON）

bash

python scripts/jenkins_deploy.py \
  <project_name> \
  --trigger-only-no-monitor \
  --yes \
  --params "<json>"

返回 JSON：

json

{
  "queue_id": 161484,
  "full_name": "abc-his/test/PcFeatureTest",
  "project_name": "PcFeatureTest",
  "build_url": "http://ci.abczs.cn/job/abc-his/job/test/job/PcFeatureTest/"
}

步骤 2：启动后台监控

Claude Code（使用 run_in_background=true）：

bash

undefined

Step 1: Trigger Build (Returns JSON)

bash

python scripts/jenkins_deploy.py \
  <project_name> \
  --trigger-only-no-monitor \
  --yes \
  --params "<json>"

Returned JSON:

json

{
  "queue_id": 161484,
  "full_name": "abc-his/test/PcFeatureTest",
  "project_name": "PcFeatureTest",
  "build_url": "http://ci.abczs.cn/job/abc-his/job/test/job/PcFeatureTest/"
}

Step 2: Start Background Monitoring

Claude Code (Use run_in_background=true):

bash

undefined

在 Claude Code 中使用 Bash 工具，设置 run_in_background=true

Use Bash tool in Claude Code, set run_in_background=true

python scripts/jenkins_deploy.py
--monitor-only
--full-name abc-his/test/PcFeatureTest
--queue-id 161484
--display-name PcFeatureTest


**其他 AI 工具或终端（使用 nohup）：**
```bash
nohup python scripts/jenkins_deploy.py \
  --monitor-only \
  --full-name abc-his/test/PcFeatureTest \
  --queue-id 161484 \
  --display-name PcFeatureTest > /dev/null 2>&1 &

重要说明：

监控任务作为后台任务运行，不阻塞主对话/终端
Claude Code：进度显示在后台任务输出中
其他工具：使用
```
nohup
```
实现后台运行，构建完成后会收到系统通知
用户可以继续进行其他操作

监控输出示例：

📊 开始监控构建: PcFeatureTest
   Queue ID: 161484
   项目: abc-his/test/PcFeatureTest

任务开始执行 (Build #11122)
📦 构建号: #11122
⏳ 监控构建进度...
   需要取消时，请告诉我: "取消构建 #11122"

⏳ [███████████░░░░░░░░░░░░░░░] 42% (125s)
...
✅ PcFeatureTest 构建成功!

python scripts/jenkins_deploy.py
--monitor-only
--full-name abc-his/test/PcFeatureTest
--queue-id 161484
--display-name PcFeatureTest


**Other AI Tools or Terminal (Use nohup):**
```bash
nohup python scripts/jenkins_deploy.py \
  --monitor-only \
  --full-name abc-his/test/PcFeatureTest \
  --queue-id 161484 \
  --display-name PcFeatureTest > /dev/null 2>&1 &

Important Notes:

The monitoring task runs as a background task and does not block the main conversation/terminal
Claude Code: Progress is displayed in the background task output
Other tools: Use
```
nohup
```
to run in the background, you will receive a system notification when the build is completed
Users can continue with other operations

Monitoring Output Example:

📊 Starting build monitoring: PcFeatureTest
   Queue ID: 161484
   Project: abc-his/test/PcFeatureTest

Task execution started (Build #11122)
📦 Build Number: #11122
⏳ Monitoring build progress...
   To cancel, please tell me: "Cancel build #11122"

⏳ [███████████░░░░░░░░░░░░░░░] 42% (125s)
...
✅ PcFeatureTest build succeeded!

参数说明

Parameter Description

--trigger-only-no-monitor 模式（触发构建）

--trigger-only-no-monitor Mode (Trigger Build)

参数	必填	说明
`project_name`	✓	Jenkins 项目名称（如 PcFeatureTest）
`--trigger-only-no-monitor`	✓	仅触发构建，不启动监控，返回 JSON
`--yes`	✓	跳过交互式确认
`--params`	✓	JSON 格式的完整构建参数

Parameter	Required	Description
`project_name`	✓	Jenkins project name (e.g., PcFeatureTest)
`--trigger-only-no-monitor`	✓	Only trigger build, do not start monitoring, returns JSON
`--yes`	✓	Skip interactive confirmation
`--params`	✓	Complete build parameters in JSON format

--monitor-only 模式

--monitor-only Mode

参数	必填	说明
`--monitor-only`	✓	后台监控模式
`--full-name`	✓	项目完整路径（如 abc-his/test/PcFeatureTest）
`--queue-id`	✓	队列 ID
`--display-name`	✓	项目显示名称（用于通知）

Parameter	Required	Description
`--monitor-only`	✓	Background monitoring mode
`--full-name`	✓	Full project path (e.g., abc-his/test/PcFeatureTest)
`--queue-id`	✓	Queue ID
`--display-name`	✓	Project display name (for notifications)

完整示例

Complete Examples

测试环境发布

Test Environment Deployment

bash

undefined

bash

undefined

步骤 1: 触发构建

Step 1: Trigger build

python scripts/jenkins_deploy.py
PcFeatureTest
--trigger-only-no-monitor
--yes
--params '{"repoTag":"pc-t2025.53.19","tapdId":"1167459320001118371","featureNo":"70"}'

返回 JSON:

Returned JSON:

{"queue_id": 161484, "full_name": "abc-his/test/PcFeatureTest", ...}

步骤 2: 启动后台监控

Step 2: Start background monitoring

Claude Code: 直接运行（会使用 run_in_background=true）

Claude Code: Run directly (will use run_in_background=true)

其他工具: 添加 nohup 和 & 放到后台

Other tools: Add nohup and & to run in background

python scripts/jenkins_deploy.py
--monitor-only
--full-name abc-his/test/PcFeatureTest
--queue-id 161484
--display-name PcFeatureTest

undefined

python scripts/jenkins_deploy.py
--monitor-only
--full-name abc-his/test/PcFeatureTest
--queue-id 161484
--display-name PcFeatureTest

undefined

开发环境发布

Development Environment Deployment

bash

python scripts/jenkins_deploy.py \
  staticPcOwn \
  --trigger-only-no-monitor \
  --yes \
  --params '{"repoBranch":"hotfix/xxx-1167459320001118371"}'

bash

python scripts/jenkins_deploy.py \
  staticPcOwn \
  --trigger-only-no-monitor \
  --yes \
  --params '{"repoBranch":"hotfix/xxx-1167459320001118371"}'

其他命令

Other Commands

bash

undefined

bash

undefined

列出所有项目

List all projects

python scripts/jenkins_deploy.py --list --all

列出当前仓库相关的项目（自动过滤）

List projects related to current repository (automatic filtering)

python scripts/jenkins_deploy.py --list

停止指定构建号

Stop specified build number

python scripts/jenkins_deploy.py --stop <build_number>

undefined

python scripts/jenkins_deploy.py --stop <build_number>

undefined

测试与验证

Testing and Validation

每次修改技能后，建议按以下流程验证：

After each skill modification, it is recommended to verify following this process:

快速测试命令

Quick Test Command

bash

undefined

bash

undefined

自动化运行所有测试用例

Automatically run all test cases

python scripts/run_tests.py

undefined

python scripts/run_tests.py

undefined

手动测试

Manual Testing

1. 参数验证（必做）

bash

python scripts/jenkins_deploy.py \
  PcFeatureTest \
  --validate \
  --params '{"repoTag":"pc-t2025.53.19","featureNo":"70"}'

2. 模拟运行（必做）

bash

python scripts/jenkins_deploy.py \
  PcFeatureTest \
  --dry-run \
  --params '{"repoTag":"pc-t2025.53.19","featureNo":"70"}'

详细测试用例：参见 test-cases.md

1. Parameter Validation (Mandatory)

bash

python scripts/jenkins_deploy.py \
  PcFeatureTest \
  --validate \
  --params '{"repoTag":"pc-t2025.53.19","featureNo":"70"}'

2. Dry Run (Mandatory)

bash

python scripts/jenkins_deploy.py \
  PcFeatureTest \
  --dry-run \
  --params '{"repoTag":"pc-t2025.53.19","featureNo":"70"}'

Detailed Test Cases: See test-cases.md

工作流程（推荐模式）

Workflow (Recommended Mode)

┌─────────────────────────────────────────────────────────────┐
│ 1. Claude Code: 使用 AskUserQuestion 收集参数               │
│    其他 AI 工具: 通过对话收集参数                            │
│    - 项目名称                                               │
│    - Git 分支 / 标签                                         │
│    - TAPD ID（从分支名自动解析）                             │
│    - featureNo（如果项目有此参数，**必填**）                 │
│    - 其他构建参数                                            │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 调用脚本 --trigger-only 模式                            │
│    - 传递完整的 JSON 参数                                    │
│    - 直接触发 Jenkins API                                   │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 返回构建信息                                            │
│    - Queue ID                                               │
│    - 构建页面 URL                                           │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 1. Claude Code: Use AskUserQuestion to collect parameters   │
│    Other AI Tools: Collect parameters through conversation  │
│    - Project Name                                           │
│    - Git Branch / Tag                                       │
│    - TAPD ID (automatically parsed from branch name)        │
│    - featureNo (**required** if the project has this parameter) │
│    - Other build parameters                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Call script in --trigger-only mode                       │
│    - Pass complete JSON parameters                          │
│    - Directly trigger Jenkins API                           │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Return build information                                │
│    - Queue ID                                               │
│    - Build page URL                                         │
└─────────────────────────────────────────────────────────────┘

智能参数推断

Intelligent Parameter Inference

参数	推断规则	示例
`repoBranch`	当前 Git 分支	`hotfix/盘点页面增加备注及搜索-1167459320001118371`
`repoTag`	最新 Git 标签	`pc-f2026.05.48`
`tapdId` / `tapdid`	从分支名自动解析（标准化流程：分支名末尾的数字）	`1167459320001118371`
`execType`	有 tag=deploy，无 tag=build	有 tag → `deploy`
`featureNo`	必填（当项目有此参数时），需用户明确指定	`1122044681001112866`
`envNo`	部分项目需要，需用户明确指定	`001`

Parameter	Inference Rule	Example
`repoBranch`	Current Git branch	`hotfix/盘点页面增加备注及搜索-1167459320001118371`
`repoTag`	Latest Git tag	`pc-f2026.05.48`
`tapdId` / `tapdid`	Automatically parsed from branch name (standard process: numbers at the end of branch name)	`1167459320001118371`
`execType`	deploy if tag exists, build if no tag	deploy if tag exists → `deploy`
`featureNo`	Required (if the project has this parameter), must be explicitly specified by user	`1122044681001112866`
`envNo`	Required for some projects, must be explicitly specified by user	`001`

TAPD ID 自动解析

TAPD ID Automatic Parsing

标准化流程下，分支名格式为

feature/xxx-{TAPD_ID}

或

hotfix/xxx-{TAPD_ID}

：

分支名：hotfix/盘点页面增加备注及搜索-1167459320001118371
                                         └────────────────────┘
                                          自动提取 TAPD ID

无需手动配置，发布时会自动填充到

tapdId

或

tapdid

参数。

⚠️ 重要：

```
featureNo
```
（功能编号）：当项目有此参数时必填，需由用户提供
```
envNo
```
（环境编号）：部分项目需要，需由用户提供

Under standard process, branch name format is

feature/xxx-{TAPD_ID}

hotfix/xxx-{TAPD_ID}

Branch name: hotfix/盘点页面增加备注及搜索-1167459320001118371
                                         └────────────────────┘
                                          Automatically extract TAPD ID

No manual configuration needed, it will be automatically filled into

tapdId

tapdid

parameter during deployment.

⚠️ Important:

```
featureNo
```
(Feature Number): Required if the project has this parameter, must be provided by user
```
envNo
```
(Environment Number): Required for some projects, must be provided by user

支持的参数类型

Supported Parameter Types

参数类型	说明	交互方式
`StringParameterDefinition`	文本输入	直接输入或回车使用默认值
`ChoiceParameterDefinition`	下拉选择	显示选项列表，输入编号选择
`PT_CHECKBOX`	复选框多选	显示选项列表，输入逗号分隔的编号
`BooleanParameterDefinition`	布尔值	y/n 选择
`WReadonlyStringParameterDefinition`	只读参数	自动使用，不可修改

Parameter Type	Description	Interaction Method
`StringParameterDefinition`	Text input	Direct input or press Enter to use default value
`ChoiceParameterDefinition`	Dropdown selection	Display option list, select by entering number
`PT_CHECKBOX`	Multiple selection via checkbox	Display option list, enter comma-separated numbers
`BooleanParameterDefinition`	Boolean value	Select y/n
`WReadonlyStringParameterDefinition`	Read-only parameter	Automatically used, cannot be modified

常见项目类型

Common Project Types

详细项目参数参考：参见 projects.md

Detailed Project Parameter Reference: See projects.md

1. PcFeatureTest (测试环境发布)

1. PcFeatureTest (Test Environment Deployment)

用途：使用标签发布到测试环境

关键参数：

```
repoTag
```
：发布标签（如
```
pc-t2025.53.19
```
）
```
tapdId
```
：TAPD 需求 ID（自动从分支名解析）
```
featureNo
```
：功能编号（必填），需用户提供
```
buildEnv
```
：固定为
```
test
```

示例：

bash

python scripts/jenkins_deploy.py \
  PcFeatureTest \
  --trigger-only \
  --params '{"repoTag":"pc-f2026.05.48","tapdId":"1167459320001118371","featureNo":"1122044681001112866"}'

Purpose: Deploy to test environment using tags

Key Parameters:

```
repoTag
```
: Deployment tag (e.g.,
```
pc-t2025.53.19
```
)
```
tapdId
```
: TAPD requirement ID (automatically parsed from branch name)
```
featureNo
```
: Feature Number (Required), must be provided by user
```
buildEnv
```
: Fixed as
```
test
```

Example:

bash

python scripts/jenkins_deploy.py \
  PcFeatureTest \
  --trigger-only \
  --params '{"repoTag":"pc-f2026.05.48","tapdId":"1167459320001118371","featureNo":"1122044681001112866"}'

2. staticPcOwn (开发环境发布)

2. staticPcOwn (Development Environment Deployment)

用途：使用分支发布到开发环境

关键参数：

repoBranch

：发布分支（如

hotfix/xxx-1167459320001118371

）

```
dockerTag
```
：Docker 镜像标签（默认
```
latest
```
）
```
buildEnv
```
：固定为
```
dev
```

示例：

bash

python scripts/jenkins_deploy.py staticPcOwn

Purpose: Deploy to development environment using branches

Key Parameters:

repoBranch

: Deployment branch (e.g.,

hotfix/xxx-1167459320001118371

)

```
dockerTag
```
: Docker image tag (default
```
latest
```
)
```
buildEnv
```
: Fixed as
```
dev
```

Example:

bash

python scripts/jenkins_deploy.py staticPcOwn

3. static-mf-deepseek (微服务发布)

3. static-mf-deepseek (Microservice Deployment)

用途：微服务项目发布，支持多区域部署

关键参数：

```
projectRootDir
```
：项目子目录（如
```
packages/mf-deepseek
```
）
```
deployZone
```
：部署区域（复选框：
```
primary
```
/
```
standby
```
）
```
repoBranch
```
：发布分支

示例：

bash

python scripts/jenkins_deploy.py static-mf-deepseek

Purpose: Microservice project deployment, supports multi-region deployment

Key Parameters:

```
projectRootDir
```
: Project subdirectory (e.g.,
```
packages/mf-deepseek
```
)
```
deployZone
```
: Deployment zone (checkbox:
```
primary
```
/
```
standby
```
)
```
repoBranch
```
: Deployment branch

Example:

bash

python scripts/jenkins_deploy.py static-mf-deepseek

缓存机制

Caching Mechanism

缓存位置：

scripts/cache/jobs.json

缓存策略：

首次运行：从 Jenkins API 获取 542 个项目并缓存
后续运行：直接使用缓存（速度快）
强制刷新：使用
```
--refresh
```
参数

手动清除缓存：

bash

rm scripts/cache/jobs.json

Cache Location:

scripts/cache/jobs.json

Cache Strategy:

First run: Retrieve 542 projects from Jenkins API and cache them
Subsequent runs: Directly use cache (faster speed)
Force refresh: Use
```
--refresh
```
parameter

Manual Cache Clear:

bash

rm scripts/cache/jobs.json

支持的 Jenkins 环境

Supported Jenkins Environments

环境	Dev	Test
abc-his	✓	✓
abc-bis	✓	✓
abc-cooperation	✓	✓
abc-global	✓	✓
abc-oa	✓	✓
mira	✓	✓

Environment	Dev	Test
abc-his	✓	✓
abc-bis	✓	✓
abc-cooperation	✓	✓
abc-global	✓	✓
abc-oa	✓	✓
mira	✓	✓

错误处理

Error Handling

场景	处理方式
未配置认证	提示设置 `JENKINS_USER` 和 `JENKINS_TOKEN`
项目不存在	列出可用项目
缺少 featureNo	如果项目有此参数，必须提示用户提供
构建失败	显示构建 URL 和日志链接
参数验证失败	提示正确格式
网络超时	提示检查网络连接

Scenario	Handling Method
Authentication not configured	Prompt to set `JENKINS_USER` and `JENKINS_TOKEN`
Project does not exist	List available projects
Missing featureNo	If the project has this parameter, must prompt user to provide it
Build failed	Display build URL and log link
Parameter validation failed	Prompt correct format
Network timeout	Prompt to check network connection

触发关键词

Trigger Keywords

Jenkins、发布、部署、构建、Deploy、Build、CI/CD

Jenkins, Deploy, Deployment, Build, CI/CD