jira-integration

name	jira_integration
description	Skill tích hợp Jira/Xray — lấy requirements từ Jira, xác thực Xray, và đẩy kết quả test lên Xray Cloud/Server.

Jira & Xray Integration Skill

Mô tả

Skill này cung cấp khả năng tích hợp giữa Antigravity Testing Kit với hệ thống Jira và Xray để:

1. Lấy Requirements/User Stories từ Jira → chuyển thành tài liệu yêu cầu chuẩn
2. Xác thực Xray (Cloud hoặc Server/Data Center)
3. Đẩy kết quả test (Playwright, JUnit, Allure) lên Xray Test Management

---

Khi nào sử dụng

Agent sử dụng skill này khi user yêu cầu:

• Lấy requirement / user story từ Jira
• Kết nối / test connection đến Jira API
• Đẩy kết quả test lên Xray
• Import test results lên Jira
• Xác thực Xray token
• Tích hợp CI/CD với Jira

Trigger keywords:

• "fetch jira", "lấy requirement từ jira", "get jira ticket"
• "import xray", "đẩy kết quả lên xray", "push test results"
• "test jira connection", "kiểm tra kết nối jira"

---

Cấu trúc Scripts

scripts/integrations/
├── jira/
│   ├── jira_fetcher.js      # Lấy Requirement/User Story từ Jira
│   ├── xray_auth.js         # Xác thực và lấy Token Xray
│   ├── xray_importer.js     # Import kết quả test lên Xray
│   └── utils.js             # Hàm utility dùng chung
└── package.json             # Dependencies (axios, dotenv)

---

Điều kiện tiên quyết (Prerequisites)

1. Cài đặt dependencies

cd scripts/integrations
npm install

2. Cấu hình .env

Copy .env.example thành .env ở thư mục gốc project:

cp .env.example .env

Điền các thông tin bắt buộc:

Biến	Mô tả	Bắt buộc
JIRA_BASE_URL	URL Jira instance (VD: https://domain.atlassian.net)	✅
JIRA_EMAIL	Email tài khoản Jira (Cloud)	✅ (Cloud)
JIRA_API_TOKEN	API Token (Cloud)	✅ (Cloud)
JIRA_PAT	Personal Access Token (Server/DC)	✅ (Server)
JIRA_PROJECT_KEY	Project key mặc định	Khuyến nghị
XRAY_PLATFORM	cloud hoặc server	Mặc định: cloud
XRAY_CLIENT_ID	Xray API Client ID	Khi dùng Xray Cloud
XRAY_CLIENT_SECRET	Xray API Client Secret	Khi dùng Xray Cloud

3. Cách lấy Jira API Token (Cloud)

1. Đăng nhập vào https://id.atlassian.com/manage-profile/security/api-tokens
2. Nhấn Create API token
3. Đặt label (VD: "Antigravity Automation")
4. Copy token → dán vào JIRA_API_TOKEN trong file .env

4. Cách lấy Xray Cloud API Key

1. Truy cập https://app.getxray.app → Settings → API Keys
2. Hoặc trong Jira: Apps → Xray → Settings → API Keys
3. Tạo API Key mới → Copy Client ID và Client Secret

---

Hướng dẫn sử dụng

Lấy 1 issue cụ thể

node scripts/integrations/jira/jira_fetcher.js --issue PROJ-123

Lấy issues theo project

node scripts/integrations/jira/jira_fetcher.js --project PROJ --type Story --max 20

Tìm theo JQL

node scripts/integrations/jira/jira_fetcher.js --jql "project = PROJ AND status = 'To Do'"

Xuất thành Markdown requirement

node scripts/integrations/jira/jira_fetcher.js --issue PROJ-123 --format md

Lấy children của Epic

node scripts/integrations/jira/jira_fetcher.js --epic PROJ-10 --format md

Test Xray authentication

node scripts/integrations/jira/xray_auth.js
node scripts/integrations/jira/xray_auth.js --verify

Import kết quả Playwright lên Xray

node scripts/integrations/jira/xray_importer.js --format playwright --file ./test-results.json --project PROJ

Import JUnit XML lên Xray

node scripts/integrations/jira/xray_importer.js --format junit --file ./junit-results.xml --project PROJ

---

Workflow liên quan

Workflow	Mô tả
/fetch_jira_requirements	Lấy requirements từ Jira ticket và lưu thành file
/import_test_results_xray	Đẩy kết quả test lên Xray

---

Lưu ý quan trọng

• Bảo mật: KHÔNG bao giờ commit file .env lên Git. File .gitignore đã được cấu hình bỏ qua .env.
• Rate Limiting: Jira Cloud có giới hạn API calls. Script đã hỗ trợ phân trang (pagination) để tránh vượt limit.
• Atlassian Document Format (ADF): Jira Cloud sử dụng ADF cho description. Script tự động chuyển đổi ADF → plain text.
• Test Key Convention: Khi import Playwright results, nên đặt test key trong title: test('[PROJ-123] Login should work', ...) để Xray mapping đúng test case.

---

Troubleshooting

Lỗi	Nguyên nhân	Giải pháp
HTTP 401	Token/password sai	Kiểm tra JIRA_API_TOKEN hoặc JIRA_PAT
HTTP 403	Không có quyền	Kiểm tra permission trên Jira project
HTTP 404	URL sai hoặc issue không tồn tại	Kiểm tra JIRA_BASE_URL và issue key
ENOTFOUND	DNS không resolve	Kiểm tra JIRA_BASE_URL có đúng domain không
ECONNREFUSED	Server không chạy	Kiểm tra Jira Server có online không
File .env not found	Chưa tạo .env	Copy .env.example → .env