Long CLI

一个面向 Bitbucket + Jenkins 的自动化部署 CLI，内置 Web 配置中心，让你从"打 Tag、等构建、触发 Jenkins、追日志"这条链路里彻底解放出来。

A CLI for automating Bitbucket + Jenkins deployment, with a built-in Web configuration center. Stop manually cutting tags, watching pipelines and triggering Jenkins jobs.

简体中文 · English

简体中文

特性

• Web 配置中心：long config 启动本地 Web UI，可视化管理凭证、项目、环境、流水线和部署历史
• CLI 与 Web 同源：命令行和 Web 走同一条部署链路，结果一致
• AWS CodeBuild 严格校验：可配置"必需的构建状态"，等所有真实 CI 通过再触发 Jenkins，杜绝部署半成品导致的 502
• 多 Jenkins 实例：不同环境可绑定不同 Jenkins Server
• 参数组批量部署：一次流水线执行多组参数（例：同一份代码分发到多个品牌）
• 智能 Tag 生成：按前缀自动递增，或写自定义函数生成任意规则
• 部署历史与日志留痕：每次部署自动落库，守护进程重启也不丢
• Bitbucket API 驱动：主流程无需本地 Git 仓库

安装

npm install -g long-git-cli

Node ≥ 16。

使用

long config       # 启动 Web 配置中心（http://127.0.0.1:3456）
long deploy       # 交互式触发部署
long tag          # 独立 Tag 工具
long commit       # 交互式规范化 commit
long --help       # 查看所有命令

首次使用建议先跑 long config，通过 Web UI 完成：

1. 凭证 — 填 Bitbucket API Token 与 Jenkins Token
2. 项目 — 粘贴 Bitbucket 仓库地址，自动解析 workspace / repoSlug
3. 环境 — 新建 test01、uat 等，绑定 Jenkins Job 和 tag 前缀
4. 流水线 — 组合 "项目 + 环境 + 分支" 作为部署入口

之后即可从 Web UI 或 long deploy 触发部署，日志实时输出。

必需的构建状态（Required Build Statuses）

背景：接入 AWS CodeBuild 等外部 CI 的仓库，Bitbucket 自带的 Pipeline - default 秒级就 SUCCESSFUL，但 AWS CodeBuild 会晚 1~2 分钟才开始上报。若监听逻辑"拿到任意 SUCCESSFUL 就冲 Jenkins"，就会在真实产物未构建完时错误触发部署，导致服务启动后 502。

做法：项目表单的"必需的构建状态"支持多选 tag 输入：

• 新建项目默认预填 AWS CodeBuild
• 已有项目升级后此字段仍为空，行为完全不变（向后兼容）
• 关键字大小写不敏感的子串匹配，name 与 key 任一命中即视为匹配
• 部署会等待所有必需状态全部 SUCCESSFUL 才触发 Jenkins
• 未监听到的状态仅打印日志，不参与判定
• 15 分钟仍未出现即超时失败

常见问题

Q：Bitbucket Token 应该配什么权限？
A：API Token（ATAT 开头）至少需要 account:read / repository:read / pullrequest:read。

Q：部署完服务出现 502？
A：触发 Jenkins 时真实产物还未构建完。给项目配上"必需的构建状态"（如 AWS CodeBuild）即可杜绝。

Q：升级到新版包后行为没变？
A：long deploy 会拉起后台守护进程长驻内存。v2.0.6+ 会自动检测版本不一致并请求守护进程重启。若未生效，pkill -f "long-git-cli.*daemon" 后重试。

Q：Jenkins 里看到参数是 tag，但传参没生效？
A：页面显示名 ≠ 实际参数名。用环境配置里的"读取 Jenkins 参数"按钮拉取真实定义，通常是 TAG_VERSION 之类。

Q：一次触发多环境 / 多品牌部署？
A：使用参数组功能，一条流水线可配多组参数，一次跑完所有组合。

License

MIT

English

Features

• Web configuration center — long config launches a local Web UI to manage credentials, projects, environments, pipelines and history
• Unified CLI & Web — Both go through the same deployment logic, so results stay consistent
• AWS CodeBuild strict gating — Configure "required build statuses" to wait until real CI reports SUCCESSFUL before triggering Jenkins, preventing 502s from half-built artifacts
• Multi-Jenkins instances — Bind different environments to different Jenkins servers
• Batch parameter sets — Run one pipeline with multiple parameter groups
• Smart tag generation — Auto-increment by prefix, or plug in a custom JS function
• Deployment history & logs — Every run persists tag / build number / full logs
• Bitbucket API driven — No local Git checkout required

Install

npm install -g long-git-cli

Requires Node ≥ 16.

Usage

long config       # Launch the Web configuration center (http://127.0.0.1:3456)
long deploy       # Trigger a deployment interactively
long tag          # Standalone tag tool
long commit       # Interactive conventional commit
long --help       # List all commands

Start with long config to set up via the Web UI:

1. Credentials — Bitbucket API Token & Jenkins Token
2. Project — Paste the Bitbucket repo URL, workspace / repoSlug auto-parsed
3. Environment — Create test01, uat, etc., bind Jenkins Job and tag prefix
4. Pipeline — Combine "project + environment + branch" as the deployment entry

Then trigger deployments either from the Web UI or via long deploy — logs stream live.

Required Build Statuses

Why: When AWS CodeBuild is wired into a Bitbucket repo, the native Pipeline - default reports SUCCESSFUL in seconds, but AWS CodeBuild only starts reporting 1~2 minutes later. Naive "trigger Jenkins on any SUCCESSFUL" logic deploys half-built artifacts → 502.

How: The project form has a "Required build statuses" multi-select input:

• New projects are pre-filled with AWS CodeBuild
• Existing projects keep the field empty after upgrade (fully backward-compatible)
• Case-insensitive substring match against status name and key
• Deployment waits until all configured statuses reach SUCCESSFUL before triggering Jenkins
• Non-matched statuses are logged but don't affect the verdict
• 15-minute timeout if a required status never appears

FAQ

Q: What Bitbucket Token permissions do I need?
A: API Token (starts with ATAT) with account:read / repository:read / pullrequest:read.

Q: 502 after deployment?
A: Jenkins was triggered before real artifacts were ready. Configure "required build statuses" (e.g. AWS CodeBuild) on the project.

Q: Upgraded the package but behavior didn't change?
A: long deploy spawns a long-lived daemon. v2.0.6+ auto-restarts the daemon on version mismatch. Otherwise: pkill -f "long-git-cli.*daemon" and retry.

Q: Jenkins shows a parameter as tag but my value doesn't get through?
A: Display name ≠ real parameter name. Use "Read Jenkins parameters" in the environment editor — the real name is often TAG_VERSION.

Q: Deploy to multiple environments or brands in one go?
A: Use parameter sets — one pipeline carries multiple parameter groups and runs them all in a single execution.

License

MIT