Jira

Soạn bug từ issue khi chạy và gửi lên Jira Cloud sau khi bạn xác nhận.

Astra Scout gom các issue của một run hoặc một lần khám phá, soạn bản nháp bug từ chính dữ liệu của run, rồi gửi lên Jira Cloud sau khi bạn xác nhận. Không có gì được gửi nếu bạn chưa đồng ý.

Admin: tạo app OAuth (một lần)

Người có quyền tạo app Atlassian, thường là Jira admin, làm một lần cho cả công ty.

1. Mở Atlassian developer console, bấm Create → OAuth 2.0 integration và đặt tên, ví dụ Astra Scout.

2. Ở Permissions, thêm Jira API và cấu hình các classic scope sau: read:jira-work, write:jira-work và read:jira-user. Astra Scout tự xin offline_access.

3. Ở Authorization, cấu hình OAuth 2.0 (3LO) và nhập Callback URL này đúng từng ký tự:

   http://127.0.0.1:47219/callback

   Nếu cổng bị chiếm, đặt SCOUT_JIRA_CALLBACK_PORT=<cổng> và đăng ký http://127.0.0.1:<cổng>/callback thay thế.

4. Ở Settings, sao chép Client ID và Secret.

5. Ở Distribution, chỉ bật Sharing nếu người dùng thuộc site khác với tài khoản đã tạo app.

6. Đưa Client ID và Secret cho tester theo một trong các cách sau (không bao giờ commit chúng):

   • Lúc build: SCOUT_JIRA_CLIENT_ID=… SCOUT_JIRA_CLIENT_SECRET=… ./scripts/build-stage.sh (hoặc build-mac-app.sh --release). Các giá trị được nhúng vào binary server, nên chỉ dùng cho bản phát hành nội bộ.
   • Lúc chạy: đặt cùng các biến đó cho tiến trình Astra Scout, ví dụ bằng launchctl setenv. Chúng thắng giá trị lúc build.
   • Trong app: Settings → Jira, ở trang App OAuth, ô Client ID và Client secret. Secret được lưu mã hoá và không hiện lại.

Tester: kết nối

1. Mở Settings → Jira và bấm Kết nối. Trình duyệt của bạn mở trang đồng ý của Atlassian. Chọn site và Accept.
2. Quay lại Astra Scout, mở File → Cài đặt dự án… (Option+Cmd+,) và, ở mục Jira, chọn Dự án, Loại issue (mặc định Bug), Nhãn mặc định, Components và Ngôn ngữ bug (Tiếng Việt hoặc English). Các giá trị này được lưu trong workspace, nên ai mở dự án cũng báo bug vào cùng một dự án Jira.

Ngắt kết nối xoá mọi bí mật Jira trên máy: refresh token và client secret đã nhập trong Settings. Để thu hồi hẳn app, vào https://id.atlassian.com/manage-profile/apps.

Access token chỉ nằm trong bộ nhớ của server. Refresh token được lưu mã hoá bằng một key giữ trong Keychain của macOS, chỉ app Astra Scout đã ký đọc được. Nó xoay vòng mỗi lần làm mới và hết hạn sau 90 ngày không dùng, khi đó bạn bấm Kết nối lại.

Gửi bug

Trên run Fail, Chưa chắc chắn hoặc Pass kèm warning, hoặc trên một lần khám phá có issue, bấm Báo bug lên Jira…, hoặc chọn Device → Báo bug lên Jira… (Shift+Cmd+B). Trên một dòng của navigator Test run, mục Báo bug lên Jira… trong menu chuột phải cũng làm như vậy. Hộp thoại liệt kê mỗi issue khác nhau một dòng:

Issue	Chọn sẵn mặc định
Step fail đã làm flow dừng	Có
Một crash (gộp với step fail khi crash là nguyên nhân)	Có
Một step optional fail	Không
Một phép kiểm tra *WithAI fail (optional) hoặc chưa chắc chắn	Không
Một rule tracking fail hoặc warning	Error: có. Warning: không.
Run workspace: mỗi flow fail (các fail giống hệt được gộp)	Tuỳ loại
Issue của khám phá	Có
Warning của khám phá	Không

Run bị chặn hoặc có mã lý do không được đề xuất như bug của app.

Mỗi dòng có tiêu đề và tóm tắt có thể sửa, các dữ kiện Astra Scout đã ghi (các step, mong đợi và thực tế, device, OS, app id và phiên bản, phiên bản Astra Scout, crash), và các file đính kèm bạn có thể tick:

• Một đoạn video quanh step fail, và ảnh chụp màn hình trước và sau (cắt bằng ffmpeg nếu có).
• Báo cáo crash (.ips trên iOS, trích đoạn logcat trên Android) và kết quả tracking.
• YAML của flow và báo cáo của run.

Đánh dấu hoặc bỏ dấu ô chọn của một dòng để chọn thứ sẽ được gửi, và dùng Mở rộng để xem chi tiết. Gõ vào Ghi chú thêm để thêm một dòng vào mọi issue (không bắt buộc). Dòng dưới số đếm cho biết đã chọn bao nhiêu bug. Bạn có thể nhờ AI viết lại tiêu đề và tóm tắt bằng Viết lại Tiêu đề và Tóm tắt bằng AI. Nếu AI thêm dữ kiện không có trong run, Astra Scout giữ nguyên văn bản gốc của bạn.

Bấm Gửi. Astra Scout hiện một hộp thoại native liệt kê chính xác những gì sẽ được gửi đi đâu. Mỗi issue được chọn trở thành một issue riêng, các issue từ cùng một lần gửi được liên kết "relates to", và issue key được ghi vào báo cáo của run.

Trùng lặp

Mỗi issue có một nhãn dấu vân tay scout-fp-<12 hex>. Trước khi gửi, Astra Scout tìm trong dự án một issue đang mở có cùng dấu vân tay. Nếu có, dòng đó đề xuất Thêm comment + file đính kèm vào KEY-12 thay vì tạo issue mới. Issue mới mang dấu vân tay, astra-scout và các nhãn mặc định của bạn.

Che dữ liệu nhạy cảm (redaction)

Mọi thứ được gửi đều đi qua một bộ che dữ liệu:

• Giá trị môi trường, text đã gõ (inputText, setClipboard) và bất cứ thứ gì có tên như password, secret, token hoặc apikey trở thành ***.
• Đường dẫn tuyệt đối trở thành <workspace>/… hoặc ~/…, và đường dẫn temp trở thành <tmp>/….
• YAML và báo cáo đính kèm là bản đã che.
• Bí mật được so khớp trong nhiều kiểu mã hoá (JSON, HTML, percent-encoding, dạng Unicode, không phân biệt hoa thường, đoạn bị cắt cụt), và bộ che nghiêng về phía che thừa.

Xem lại trước khi gửi

Một số thứ không được che theo thiết kế: chuỗi literal trong evalScript hoặc runScript, text trên màn hình dùng trong selector, và đường dẫn tuyệt đối nằm ngoài thư mục home và workspace của bạn. Video và ảnh chụp màn hình có thể lộ text đã gõ. Với flow nhạy cảm, hãy bỏ tick đoạn video và ảnh chụp màn hình, hoặc để tắt tự động gửi.

Priority theo severity

Với option Đặt Priority theo severity ở mục Jira trong Cài đặt dự án, bạn có thể đặt Priority theo severity của các phát hiện khi khám phá. Mức 5 ứng với priority cao nhất trong danh sách của dự án và mức 1 ứng với thấp nhất. Nếu không đọc được danh sách, priority mặc định của dự án được dùng.

Tự động gửi crash

Tự gửi crash nằm trong Cài đặt dự án, mục Crash. Mặc định tắt. Chỉ bật được qua một hộp thoại native, và tự tắt khi Astra Scout khởi động lại. Khi bật, run làm app crash sẽ tạo một issue kèm video và log crash (đã che), nhưng chỉ khi không có issue trùng và tối đa N lần mỗi giờ (Số issue tối đa mỗi giờ, từ 1 đến 20, mặc định 3; chỉ đổi được khi đang tắt tự gửi). Nếu Astra Scout không xác định được có issue trùng hay không, nó không gửi gì.

Từ terminal

Tool MCP report_bug cho phép AI CLI chuẩn bị bản nháp, nhưng CLI không bao giờ nhận được token Jira và không thể tự gửi. Astra Scout hiện một hộp thoại xác nhận native, và yêu cầu được liệt kê là Chờ xác nhận trong Hoạt động từ CLI ở Settings → AI → Kết nối MCP. Xem Plugin scout.

Sự cố thường gặp

Triệu chứng	Cách xử lý
"Port 47219 is busy"	Đóng chương trình đang dùng nó, hoặc đặt SCOUT_JIRA_CALLBACK_PORT và đăng ký callback tương ứng.
Error redirect_uri không khớp	Callback URL của app phải đúng là http://127.0.0.1:<cổng>/callback.
"Jira session expired or revoked"	Refresh token đã bị thu hồi hoặc cũ hơn 90 ngày. Bấm Kết nối lại.
Bạn không thấy dự án	Tài khoản thiếu quyền Browse project trên site đó.
Tạo issue fail ở issuetype hoặc components	Chọn lại loại issue hoặc bỏ component không tồn tại trong dự án.
Video không được đính kèm	Video vượt giới hạn đính kèm của site. Cài ffmpeg để cắt đoạn ngắn hơn.

Lần kiểm tra thật đầu tiên

Hãy thử với một dự án test trước: chạy một flow fail, gửi bug, chạy lại (dòng đó phải đề xuất comment), rồi ngắt kết nối và xác nhận các bí mật đã bị xoá.