Jira & Xray Integration Skill

Mô tả

Skill này cung cấp khả năng tích hợp giữa Codex workspace 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:

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 (ví dụ: "Codex 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

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