jira-server-pat-cli

Jira Server / Data Center CLI

目标

为任意 Jira Server / Data Center 实例提供可迁移、可审计、无环境隐私的命令行管理方案。优先使用 Jira 官方 REST API 和运行时元数据发现，不把单个组织的配置写进 Skill。

本 Skill 附带：

• scripts/jira_cli.py：纯 Python 标准库 CLI。
• references/command-reference.md：完整命令、配置和能力边界。

使用边界

使用本 Skill：

• 用户要求通过脚本或 CLI 管理 Jira Server / Data Center。
• 实例使用 PAT、2FA、SSO、Cookie、Basic Auth、内部 CA 或自签证书。
• 任务涉及项目、issue、JQL、transition、评论、工时、附件、链接、watcher、权限或元数据。

不要直接套用本 Skill：

• Jira Cloud。Cloud 的 API token、accountId、REST v3 和 Atlassian Document Format 语义不同。
• 用户只要求 Jira Web 页面操作且不需要 REST/CLI。
• 目标接口属于第三方 Jira 插件，且尚未核对插件文档和版本。

强制隐私规则

1. 不在 Skill、脚本、示例、测试或日志中写入真实域名、IP、用户名、邮箱、项目 Key、issue Key、PAT、Cookie、自定义字段 ID、issue type ID、transition ID 或内部目录。
2. 示例只使用 jira.example.com、PROJ、PROJ-123、alice、customfield_12345 等明确占位值。
3. 不要求用户把 PAT 发到聊天中。优先让用户在本机通过 JIRA_PAT、权限为 0600 的配置文件或 secret manager 注入。
4. 不输出请求头、Cookie、PAT 或包含凭证的配置全文。报错和 debug 输出必须脱敏。
5. 不把实例探测结果写回 Skill。实例元数据只用于当前执行。
6. destructive 命令必须显式确认。附带 CLI 对 issue、评论、工时、附件、链接删除和所有 raw POST/PUT/DELETE 使用 --yes 门禁。

执行流程

1. 确认产品与版本

先确认目标是 Jira Server / Data Center，而不是 Jira Cloud。优先调用：

python3 scripts/jira_cli.py server-info

记录但不持久化：

• Jira 版本与 build number。
• Base URL 是否包含 context path，例如 /jira。
• 已安装 Jira Software 或 Jira Service Management 与否。
• REST API version 和目标 endpoint 是否存在。

不要把 /login.jsp 当成 Server/DC 的唯一识别依据。

2. 选择鉴权

优先级：

1. OAuth 2.0：适用于需要委托授权的正式集成，但配置成本高于个人 CLI。
2. PAT Bearer：个人脚本和 CLI 的首选。Jira Core/Software 8.14+、Jira Service Management 4.15+ 支持 PAT。
3. Basic Auth：仅在实例明确允许且安全策略接受时使用。
4. 浏览器 Cookie：临时排障兜底，不作为长期自动化凭证。

PAT 使用方式：

export JIRA_BASE_URL="https://jira.example.com/jira"
export JIRA_PAT="<secret>"
python3 scripts/jira_cli.py whoami

PAT 通过 Authorization: Bearer <token> 发送，不附加用户名。

如果 whoami 返回 401 或 403，不要直接断言 PAT 被 SSO 接管。依次检查：

1. PAT 是否过期、被撤销或复制不完整。
2. Base URL 和 context path 是否正确。
3. 反向代理是否保留 Authorization header。
4. Jira 版本是否支持 PAT，管理员是否禁用 PAT。
5. 用户权限或账号状态是否限制当前资源。