Chia sẻ build cho tester

Upload build cho team bằng scout-build, post-action của Xcode, CI hoặc trang web builds, và đăng ký iOS device của tester. Đọc run của team.

Dev upload build lên team. Tester chọn build trong Astra Scout và cài lên device; xem Builds. Dev không cần Astra Scout để upload. Owner quản lý member, token và iOS device của tester trên trang web builds. Cùng các project đó gắn workspace flow với team: xem Team Sync.

Vai trò

Vai trò	Làm được
Owner	Mọi việc của editor, cộng với quản lý member, upload token, UDID của tester và project
Editor	Upload build, đặt bản đề xuất, xoá build và mọi run
Tester	Xem build và cài, đưa run của mình lên team, xem mọi run và xoá run của mình. Mọi người còn lại mà danh sách truy cập cho phép đăng nhập đều là tester.

Trước khi bắt đầu

• Trang web builds: https://scout.astraler.com.
• Một project cho app trên trang đó. Owner tạo bằng Project mới… (xem Cài đặt): id, tên, và nếu muốn thì iOS bundle id và Android package của app. Khi đã điền bundle id hoặc package, mọi upload vào project phải khớp.
• Tài khoản Google của bạn được thêm làm editor hoặc owner, hoặc một upload token của project.

Trang web chỉ có giao diện tiếng Việt. Các nhãn dưới đây ghi đúng như trên trang. Mọi người thấy trang Builds và Runs. Editor thấy thêm Tester và device, owner thấy thêm Cài đặt.

Upload từ trang web

1. Mở trang web builds và bấm nút đăng nhập Google.
2. Chọn project ở menu project phía trên, rồi chọn tab iOS, iOS Simulator hoặc Android.
3. Kéo file .ipa, .apk hoặc .zip vào bất kỳ đâu trên trang, hoặc bấm Upload build. Với build simulator, dùng file .zip chứa <tên>.app.
4. Trang đọc version, bundle id, profile và danh sách iOS device từ file. Kiểm tra Version và Build, rồi thêm Ghi chú cho tester.
5. Giữ nguyên Đặt làm bản đề xuất để đề xuất bản này, rồi bấm Upload.

Nút thêm hành động ở cuối dòng build mở một menu:

Mục	Làm gì
Sửa ghi chú…	Sửa ghi chú. Xem Sửa ghi chú.
Đặt làm đề xuất	Đặt bản này làm bản đề xuất của loại đó. Khi bản đã là bản đề xuất, mục ghi Đang là đề xuất và bị mờ.
Tải .ipa	Tải file về. Với loại khác, nhãn kết thúc bằng .apk hoặc .zip.
Xoá…	Xoá build sau khi xác nhận. File bị xoá khỏi kho lưu trữ và không khôi phục được.

Ai cũng tải được. Editor và owner thấy các mục còn lại.

Kho lưu trữ tự giữ trong giới hạn: mỗi project giữ 20 bản build mới nhất của từng loại. Khi một bản mới upload xong, các bản cũ hơn bị xoá, trừ bản đề xuất và bản có người đang dùng (Scout báo bản nó cài). Xoá tay vẫn được bất cứ lúc nào.

Tìm kiếm

Ô tìm kiếm phía trên danh sách (Tìm version, ghi chú) lọc các build của tab đang mở theo version, build number và ghi chú khi bạn gõ. Khi không có gì khớp, danh sách ghi Không có build khớp “…”.

Chi tiết build

Bấm một build để mở chi tiết ở bên phải. Trên màn hình hẹp, chi tiết phủ lên danh sách và ← Danh sách đóng lại. Panel có:

• Version và build number cùng các badge, và dòng "Upload bởi" với tên, ngày và nguồn: Web, scout-build, CI, Xcode hoặc Astra Scout.
• Icon của app, lấy từ file đã upload (.ipa, .apk hoặc .zip của simulator) bởi trang web hoặc scout-build. Menu project hiện icon của build mới nhất. Build upload trước khi có tính năng này vẫn hiện glyph thường.
• Các nút ★ Đặt làm đề xuất, Tải .ipa và menu thêm hành động.
• Ghi chú cho tester.
• Chi tiết: Bundle ID, Dung lượng và SHA-256 với Sao chép. Build iOS còn có Provisioning profile (loại và ngày hết hạn) và Device trong profile (số iOS device trong profile, với xem danh sách để hiện UDID của chúng, hoặc Mọi device khi profile không có danh sách).
• Tester đang dùng: email và tên device của từng người mà Astra Scout báo đang dùng bản này. "Chưa ai báo đang dùng bản này." nghĩa là chưa có ai.

Badge của một build:

Badge	Ý nghĩa
New	Upload trong 24 giờ qua, hoặc sau lần bạn vào trang gần nhất
★ Đề xuất	Bản đề xuất của loại đó
Profile hết hạn sau N ngày	Build iOS có provisioning profile hết hạn trong 14 ngày hoặc ít hơn
Profile hết hạn	Provisioning profile đã hết hạn. Build lại với profile mới và upload.

Sửa ghi chú

Editor và owner đổi được ghi chú của build đã upload. Chọn Sửa ghi chú… trong menu của dòng hoặc của panel, hoặc bấm Sửa cạnh ghi chú. Gõ tối đa 5000 ký tự rồi bấm Lưu. Huỷ giữ ghi chú cũ. Build không có ghi chú hiện "Không có ghi chú".

Runs

Trang Runs liệt kê các run mà Astra Scout đã đưa lên team cho project đang chọn ở menu project: xem Run của team. Run mới nhất ở trên. Mỗi dòng có kết quả, flow kèm step fail, device, build, người chạy và cột Lúc chạy với thời gian chạy ở dòng dưới. Tải thêm hiện trang tiếp theo.

• Các nút Tất cả, Passed, Failed, Blocked, Unsure và Incomplete lọc theo kết quả, kèm số lượng mỗi loại.
• Lọc theo flow tìm run theo tên flow.
• Lọc theo device và Lọc theo người chạy thu hẹp danh sách.

Bấm một dòng để mở khung Chi tiết lượt chạy: Chi tiết với Flow, Bước lỗi, Thiết bị, Bản build và Bắt đầu, rồi Jira, Report với mỗi step một dòng, Ảnh, Video phát ngay trên trang và File. Run fail có ảnh Lúc lỗi đứng đầu Ảnh: màn hình device ngay khi step fail. Liên kết #/runs/<id> mở đúng run đó; dấu cloud của một run trong Astra Scout mở cùng liên kết này.

Ở Jira, nhập issue key của bug, ví dụ ABC-123, rồi bấm Lưu. Run có Jira key được giữ qua giới hạn 300 run hoặc 60 ngày. Báo bug từ Astra Scout tự điền key này.

Để xoá, mở nút thêm hành động cạnh tên flow và chọn Xoá…. Run bị gỡ cùng file và video của nó khỏi team. Tester xoá run của mình. Owner và editor xoá mọi run.

Upload bằng scout-build

scout-build upload build từ terminal, CI hoặc Xcode. Cài đặt:

curl -fsSL https://pub-41fdab24ed354d9cbc36e595de529780.r2.dev/scout-build/install.sh | sh

Script đặt scout-build vào ~/.local/bin (đổi bằng SCOUT_BUILD_DIR), kiểm tra SHA-256 và không cần sudo. CI runner Linux dùng cùng lệnh này. scout-build version in scout-build và version của nó.

Đăng nhập

Owner tạo upload token trên trang Tester và device. Ở card Token, bấm Tạo token…, giữ Loại là Upload cho một project, chọn Project, nhập Tên và bấm Tạo. Trang hiện token (sst_…) một lần, kèm lệnh login tương ứng: "Token chỉ hiện một lần. Sao chép ngay." Hộp thoại Upload tự động, mở từ Upload tự động từ Xcode hoặc CI dưới danh sách build, có các lệnh cài, login, upload và xcode-hook, kèm link Tạo token… cho owner.

scout-build login --token sst_…

login kiểm tra token và lưu vào ~/.config/scout-build/config.json. Upload token chỉ upload được vào một project và không đọc được gì khác.

Upload

scout-build upload --project <id> --notes "Fix paywall" --recommend path/to/App.ipa

Tuỳ chọn	Dùng để
--project <id>	Id của project. Bắt buộc.
path	File .ipa, .app, .xcarchive hoặc .apk. Không có path, scout-build upload bản build mới nhất khớp trong DerivedData và Archives của Xcode. Build Android luôn cần path.
--kind ios-device|ios-sim|android	Loại build. Mặc định suy ra từ file.
--notes "…"	Ghi chú hiện cùng build
--recommend	Đặt bản này làm bản đề xuất của loại đó
--source cli|ci|xcode	Nguồn upload. Mặc định cli.
--quiet	Không in tiến độ

scout-build tự đóng gói .app: .app cho device thành .ipa, .app cho simulator thành .zip. Với .xcarchive, nó upload .app đầu tiên trong Products/Applications. File .ipa phải là build cho device. Build simulator thì upload bằng .app.

Không có path, scout-build đọc iOS bundle id của project từ team API và chọn bản build mới nhất của app đó trong DerivedData và Archives. --kind giới hạn lựa chọn trong build cho device hoặc build simulator. Project phải có iOS bundle id.

Khi xong, lệnh in uploaded <project> <kind> <version> (<build>). Tester thấy bản build trong cửa sổ Builds và nhận thông báo trong vòng 5 phút.

Upload từ CI

Đặt địa chỉ và token bằng biến môi trường thay vì chạy login:

export SCOUT_API_URL=<url>
export SCOUT_UPLOAD_TOKEN=sst_…
scout-build upload --project <id> --source ci --recommend App.ipa

Thứ tự ưu tiên: tuỳ chọn --api và --token, rồi SCOUT_API_URL và SCOUT_UPLOAD_TOKEN, rồi file do login lưu.

Upload sau mỗi lần build trong Xcode

1. Chạy scout-build login trước. Xcode không truyền môi trường shell của bạn cho script.
2. Chạy scout-build xcode-hook --project <id>. Thêm --build cho action Build; mặc định là Archive.
3. Trong Xcode, chọn Product > Scheme > Edit Scheme, chọn Archive (hoặc Build), rồi Post-actions.
4. Bấm +, chọn New Run Script Action và đặt Provide build settings from là target của app.
5. Dán script mà xcode-hook đã in.

Script chứa đường dẫn của binary scout-build đã in ra nó. Log nằm ở ~/Library/Logs/scout-build.log. Khi upload lỗi, một thông báo ghi "Upload failed. See ~/Library/Logs/scout-build.log".

Đăng ký iOS device của tester

Build development hoặc Ad Hoc chỉ cài được lên iOS device có trong provisioning profile. Khi tester gửi UDID từ Astra Scout, owner đăng ký UDID và dev build lại.

1. Trên trang web, mở UDID chờ đăng ký. Trang liệt kê tên, email và UDID của từng iOS device đang chờ. scout-build devices list in cùng danh sách.

2. Tạo devices token. Ở card Token trên Tester và device, bấm Tạo token…, chọn Loại Đăng ký UDID, nhập Tên và bấm Tạo. Đăng nhập trên Mac của owner:

   scout-build login --token sst_…

3. Cung cấp cho scout-build một App Store Connect API key có vai trò Admin hoặc App Manager. Dùng các tuỳ chọn --asc-key-id, --asc-issuer-id và --asc-key (file .p8), hoặc các biến môi trường ASC_KEY_ID, ASC_ISSUER_ID và ASC_KEY_PATH. Không có issuer id, scout-build coi đó là individual key.

4. Đăng ký các iOS device:

   scout-build devices register --all

   Truyền một hoặc nhiều UDID thay cho --all để chỉ đăng ký các UDID đó. --dry-run cho xem những gì sẽ được đăng ký và không thay đổi gì.

5. Build lại app. Với automatic signing, Xcode thêm iOS device vào Development profile. Ad Hoc profile phải được tạo lại.

6. Upload bản build mới. Tester nhận thông báo và cài.

Owner đã đăng ký iOS device trong App Store Connect bằng tay thì bấm Đã đăng ký trên dòng của nó để gỡ khỏi danh sách.

Key nằm trên Mac của owner; trang web không bao giờ nhận key. Apple cho phép 100 iOS device mỗi membership year và không xoá được device, nên devices register luôn yêu cầu --all hoặc UDID cụ thể.

Sau mỗi lần devices register, và sau devices list khi chạy kèm App Store Connect key, scout-build gửi số iOS device đã đăng ký lên trang web. Owner và editor thấy số này trên card UDID chờ đăng ký, ví dụ "87 / 100 iOS device".

Member

Owner quản lý mọi người trên trang Tester và device, ở card Thành viên. Bấm Thêm thành viên…, nhập Email, chọn Vai trò (Tester, Editor hoặc Owner) và bấm Thêm. Email cũng được thêm vào danh sách đăng nhập. Ai đăng nhập được mà không có trong danh sách là tester.

Mỗi dòng cho biết người đó, bản họ đang dùng gần nhất ("Đang dùng" với version và device) hoặc lần hoạt động gần nhất. Đổi vai trò bằng nút vai trò của dòng. Để gỡ một người, mở nút thêm hành động của dòng, chọn Xoá khỏi team… và xác nhận bằng Xoá. Người đó bị gỡ khỏi danh sách member và danh sách đăng nhập. Nếu domain của họ vẫn được phép, họ đăng nhập lại với vai trò tester. Owner cuối cùng không đổi vai trò hay gỡ được.

Token

Card Token trên Tester và device liệt kê mọi token với loại (Upload · project hoặc Đăng ký UDID), ngày tạo và lần dùng gần nhất ("chưa dùng" nếu chưa). Để thu hồi, mở nút thêm hành động của dòng, chọn Thu hồi… và xác nhận bằng Thu hồi. Job scout-build hoặc CI dùng token đó bị từ chối từ lúc này. Dòng vẫn nằm trong danh sách với chữ "đã thu hồi". Chỉ owner tạo và thu hồi token.

Cài đặt

Owner thấy trang Cài đặt:

• Project: đổi tên project và đổi iOS bundle ID và Android package, rồi bấm Lưu. Huỷ đưa các ô về giá trị cũ. Id của project hiện cạnh tiêu đề và không đổi được.
• Domain được đăng nhập: nhập một domain như astraler.com vào Domain và bấm Thêm domain. Mọi email của domain đó đều đăng nhập được. Xoá… gỡ một domain; người dùng của nó không đăng nhập được nữa, trừ khi email của họ là member. Không có domain thì chỉ các email thêm riêng đăng nhập được. Không làm trống được danh sách đăng nhập.
• Project mới: bấm Project mới…, cũng có trong menu project phía trên. Nhập Id (a-z, 0-9, -), Tên và nếu muốn thì iOS bundle ID (tuỳ chọn) và Android package (tuỳ chọn), rồi bấm Tạo project. Id là giá trị --project nhận.

Đăng xuất

Bấm avatar ở góc trên bên phải. Menu hiện email và vai trò của bạn, và Đăng xuất. Khi phiên tự hết hạn, trang ghi "Phiên đăng nhập đã hết hạn, đăng nhập lại."

Xử lý sự cố

Triệu chứng	Cách sửa
"no API address or token"	Chạy scout-build login, hoặc đặt SCOUT_API_URL và SCOUT_UPLOAD_TOKEN.
"an Android build needs a path to the .apk"	Truyền đường dẫn file .apk.
project <id> has no iOS bundle id; pass the path of the build	Truyền path, hoặc nhờ owner đặt bundle id cho project.
Upload từ Xcode không xuất hiện	Đọc ~/Library/Logs/scout-build.log.
"App Store Connect key missing"	Truyền --asc-key-id và --asc-key, hoặc đặt ASC_KEY_ID và ASC_KEY_PATH.
"a simulator build cannot be an .ipa: upload the .app directory instead"	Truyền .app của build simulator.
no device build of <bundle id> found in Xcode's DerivedData or Archives; build it, or pass the path	Build app trong Xcode, hoặc truyền path.