2026-03-16 18:11:34 +08:00
|
|
|
|
# Jira 上传附件 — 配置文件说明
|
|
|
|
|
|
|
|
|
|
|
|
本技能通过脚本 `scripts/upload_attachment.py` 将影响分析报告 MD 文件上传到 Jira Issue 附件（Atlassian MCP 插件不支持上传文件）。脚本从**配置文件**或环境变量读取 Jira 认证与站点信息，环境变量可覆盖配置文件中的同名项。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 配置文件方式（推荐）
|
|
|
|
|
|
|
|
|
|
|
|
### 1. 创建配置文件
|
|
|
|
|
|
|
|
|
|
|
|
在技能目录 `skills/g3fo-commit-jira/` 下放置 `jira_upload.env`，或复制示例后改名并填写真实值：
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
# 在技能目录下
|
|
|
|
|
|
copy jira_upload.env.example jira_upload.env
|
|
|
|
|
|
# 编辑 jira_upload.env，填入 JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 文件格式
|
|
|
|
|
|
|
|
|
|
|
|
`jira_upload.env` 为 KEY=VALUE 格式，支持 `#` 注释：
|
|
|
|
|
|
|
|
|
|
|
|
```ini
|
|
|
|
|
|
# Jira 站点 URL，不要带末尾 /
|
|
|
|
|
|
JIRA_BASE_URL=https://你的站点.atlassian.net
|
|
|
|
|
|
# 登录邮箱
|
|
|
|
|
|
JIRA_EMAIL=你的邮箱@company.com
|
|
|
|
|
|
# API Token（在 Atlassian 账户设置中创建）
|
|
|
|
|
|
JIRA_API_TOKEN=你的 API Token
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 3. 指定配置文件路径
|
|
|
|
|
|
|
|
|
|
|
|
从仓库根目录执行时，建议用 `--config` 指定技能目录下的配置文件：
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
python skills/g3fo-commit-jira/scripts/upload_attachment.py --config "skills/g3fo-commit-jira/jira_upload.env" --issue G3SF-123 --file "G3SF-123_Impact_Analysis.md"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 配置项说明
|
|
|
|
|
|
|
|
|
|
|
|
| 配置项 | 说明 | 示例 |
|
|
|
|
|
|
|--------|------|------|
|
|
|
|
|
|
| `JIRA_BASE_URL` | Jira 站点 URL，不要带末尾 `/` | `https://your-domain.atlassian.net` |
|
|
|
|
|
|
| `JIRA_EMAIL` | 登录 Jira 的邮箱 | `you@company.com` |
|
|
|
|
|
|
| `JIRA_API_TOKEN` | Jira 账户的 API Token | 在 [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) 创建 |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-03-23 13:38:41 +08:00
|
|
|
|
## 无 MCP：`jira_cli.py`（查 Jira / 建单 / 评论）
|
|
|
|
|
|
|
|
|
|
|
|
在 **未安装 Atlassian MCP** 的环境（其它 IDE、终端）中，使用与上传附件**相同**的 `jira_upload.env`，通过 `scripts/jira_cli.py` 调用 Jira REST API v3：
|
|
|
|
|
|
|
|
|
|
|
|
| 子命令 | 作用 |
|
|
|
|
|
|
|--------|------|
|
|
|
|
|
|
| `myself` | 当前用户 accountId / 邮箱 |
|
|
|
|
|
|
| `search` | JQL 搜索（默认：G3SF 进行中且指派给当前用户） |
|
|
|
|
|
|
| `issue <KEY>` | 查看单条 Issue |
|
|
|
|
|
|
| `create` | 创建 Issue（默认 G3SF + Task，经办人为 Token 用户） |
|
|
|
|
|
|
| `comment` | 添加评论 |
|
|
|
|
|
|
|
|
|
|
|
|
依赖：`pip install -r scripts/requirements.txt`（仅需 `requests`）。
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
# 搜索（与技能 Step 3 默认 JQL 一致）
|
|
|
|
|
|
python skills/g3fo-commit-jira/scripts/jira_cli.py --config "skills/g3fo-commit-jira/jira_upload.env" search --limit 5
|
|
|
|
|
|
|
|
|
|
|
|
# 新建（描述来自文件）
|
|
|
|
|
|
python skills/g3fo-commit-jira/scripts/jira_cli.py --config "skills/g3fo-commit-jira/jira_upload.env" create --summary "[G3SF] 简述" --description-file "D:\tmp\impact.md"
|
|
|
|
|
|
|
|
|
|
|
|
# 评论
|
|
|
|
|
|
python skills/g3fo-commit-jira/scripts/jira_cli.py --config "skills/g3fo-commit-jira/jira_upload.env" comment --issue G3SF-123 --body-file "D:\tmp\comment.md"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
配置文件查找顺序：当前工作目录、`scripts/` 下、`skills/g3fo-commit-jira/` 下的 `jira_upload.env`。详细参数见 `references/workflow.md`「无 MCP：jira_cli 速查」。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-03-16 18:11:34 +08:00
|
|
|
|
## 环境变量覆盖
|
|
|
|
|
|
|
|
|
|
|
|
若同时存在配置文件和环境变量，**环境变量优先**。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## API Token 获取
|
|
|
|
|
|
|
|
|
|
|
|
1. 打开 https://id.atlassian.com/manage-profile/security/api-tokens
|
|
|
|
|
|
2. 使用 Jira 登录邮箱登录
|
|
|
|
|
|
3. 点击 “Create API token”，命名后复制
|
|
|
|
|
|
4. Token 只显示一次，请妥善保存
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 安全注意
|
|
|
|
|
|
|
|
|
|
|
|
- **不要将 `jira_upload.env` 提交到 Git**。技能目录下已通过 `.gitignore` 忽略。
|
|
|
|
|
|
- 不要将 `JIRA_API_TOKEN` 写入代码或提交到仓库。
|
|
|
|
|
|
- 定期在 Atlassian 账户中轮换 API Token。
|
