Xử lý sự cố lỗi GitHub

Chẩn đoán rate limit, lỗi auth, và các lỗi GitHub CLI khác trong panel PR check, Tasks, và Source Control của Orca.

Orca nói chuyện với GitHub qua GitHub CLI (gh) trên máy bạn (hoặc host Orca remote). Khi trạng thái PR, check, issue, hoặc Tasks không refresh được, nguyên nhân gần như luôn là auth GitHub, quyền, hoặc rate limit API - không phải panel PR tự nó hỏng.

Trang này liệt kê các lỗi bạn sẽ gặp nhiều nhất và cách sửa.

Triage nhanh

Bạn thấy gì	Nguyên nhân khả dĩ	Thử đầu tiên
“GitHub is rate-limiting requests” / “rate limit exceeded (core)”	Quota REST (core) của GitHub cho user của bạn đã cạn	Chờ reset; dừng dùng thêm gh / agent / Orca; kiểm tra Settings → Git → GitHub API Budget
“GitHub authentication is unavailable” / prompt gh auth	gh chưa đăng nhập, token hết hạn, hoặc GITHUB_TOKEN sai	gh auth status, rồi gh auth login
“GitHub did not allow access” / HTTP 403 (không phải rate limit)	Thiếu scope hoặc không có quyền truy cập repo	Auth lại với repo (và SSO org cần thiết); xác nhận bạn mở được PR trong trình duyệt
“repository is unavailable” / HTTP 404	Sai remote, repo private không có quyền, hoặc repo đã đổi tên	Kiểm tra git remote -v và quyền truy cập trong trình duyệt
“GitHub is unreachable” / timeout	Mạng, proxy, VPN, hoặc GitHub đang gặp sự cố	Kiểm tra githubstatus.com; thử lại khi tắt VPN
“GitHub CLI is unavailable”	gh thiếu trong PATH Orca dùng	Cài gh và khởi động lại Orca

Rate limit (thường gặp nhất)

GitHub cấp cho mỗi user đã xác thực một ngân sách hằng giờ dùng chung. Mọi tool trên tài khoản đó dùng chung ngân sách này: Orca, gh trong terminal, agent Claude/Codex/Grok gọi gh, script CI, extension trình duyệt, và các app khác.

Các bucket Orca quan tâm

Bucket	Bao gồm gì	Giới hạn điển hình (đã xác thực)
REST (core)	Hầu hết lệnh gọi PR/issue/API (gh pr view, metadata check, nhiều REST endpoint)	5.000 / giờ
GraphQL	Project/Tasks và một số query PR phong phú hơn	5.000 điểm / giờ
Search	Danh sách dựa trên search	30 / phút

Khi một bucket chính đã cạn, GitHub trả về HTTP 403 với thông báo dạng API rate limit exceeded. Orca phân loại đó là rate-limited, giữ lại trạng thái PR đã biết gần nhất khi có thể, và dừng tạo thêm lệnh gọi gh trong một khoảng ngắn để một giới hạn không biến thành một cơn bão thất bại.

Vì sao Settings có thể trông “OK” trong khi panel PR bị chặn

Settings → Git → GitHub API Budget đọc endpoint rate_limit đặc biệt của GitHub. Probe đó được miễn khỏi việc tính rate-limit và đôi khi vẫn báo còn quota trong khi các lệnh gọi REST thật cho cùng user đã trả về remaining: 0.

Khi chúng mâu thuẫn nhau, tin theo thứ tự này:

1. Lỗi trên panel PR / Checks (request live đã fail)
2. Một lần kiểm tra CLI thật (bên dưới)
3. Số liệu budget trong Settings (hữu ích, nhưng chỉ là probe)

Cũng đừng nhầm GitHub API Budget với usage Claude / Codex / Grok dưới Accounts - đó là giới hạn của provider AI, không phải quota REST của GitHub.

Xác nhận một rate limit từ terminal

# Probe (không tiêu thụ quota; có thể trông khoẻ hơn thực tế)
gh api rate_limit --jq '.resources | {core, graphql, search}'

# Lệnh gọi REST thật - đây là thứ việc refresh PR phụ thuộc vào
gh api user -i 2>&1 | head -40

Nếu gh api user trả về 403 với API rate limit exceeded và X-Ratelimit-Remaining: 0, tài khoản bị chặn REST cho tới X-Ratelimit-Reset (giây epoch Unix).

Thứ thường đốt hết quota

• Nhiều cửa sổ Orca hoặc bản build electron-dev mở cùng lúc (mỗi cái có thể tự refresh PR / Tasks)
• Agent tự động hoá gh (assign PR/issue, poll check, GraphQL hàng loạt)
• Tasks nặng / fan-out đa repo trong khi vẫn refresh panel PR
• App khác dùng chung token user GitHub

Nên làm gì

• Chờ reset hằng giờ hiện trong lỗi hoặc trong X-Ratelimit-Reset.
• Giảm số client GitHub đồng thời - thoát các instance Orca thừa và tạm dừng automation gh hàng loạt.
• Tránh liên tục bấm refresh trên panel PR khi đang bị giới hạn; Orca đã tự giảm tốc sẵn.
• Ưu tiên gộp GraphQL trong script; đừng loop REST từng PR một trên tập lớn với tài khoản cá nhân.
• Sau khi reset, nếu refresh PR vẫn thất bại, kiểm tra lại auth (mục tiếp theo).

Vấn đề xác thực

Orca kế thừa bất cứ thứ gì gh đang dùng trên host đó.

Kiểm tra trạng thái

gh auth status -h github.com
gh api user --jq '{login, id}'

Output khoẻ mạnh: đã đăng nhập, token hợp lệ, gh api user trả về login của bạn.

Các cái bẫy thường gặp

GITHUB_TOKEN / GH_TOKEN trong shell profile

Nếu các biến này được export (ví dụ export GITHUB_TOKEN=$(gh auth token) trong ~/.bash_profile hoặc ~/.zshrc), gh ưu tiên chúng hơn keyring. Một token env cũ hoặc sai gây ra hành vi auth hoặc rate-limit khó hiểu. Unset chúng và đăng nhập lại:

unset GITHUB_TOKEN GH_TOKEN
gh auth logout -h github.com
gh auth login -h github.com

Token hết hạn hoặc bị thu hồi

gh auth status có thể báo token không hợp lệ. Chạy gh auth login (hoặc gh auth refresh) và khởi động lại Orca để nó nhận credential mới.

SSO SAML của tổ chức

Repo private của org có thể cần ủy quyền SSO cho token. Mở link authorize SSO của org từ settings token GitHub, rồi thử lại.

Worktree remote / SSH

Auth GitHub tính theo từng host. Đăng nhập trên laptop không đăng nhập gh trên một máy remote. SSH vào host đó và chạy gh auth login ở đó, hoặc dùng view GitHub budget remote-server của Orca cho môi trường đó.

Lỗi quyền và repository

Triệu chứng	Ý nghĩa
HTTP 403 không có “rate limit”	Token thiếu scope hoặc bạn không được phép xem resource
HTTP 404 / “could not resolve to a Repository”	Repo thiếu, đã đổi tên, hoặc không nhìn thấy được với token này
“resource not accessible by integration”	Loại app/token không thực hiện được hành động đó

Cách sửa:

• Xác nhận PR/repo mở được trong trình duyệt khi đăng nhập cùng user với gh api user.
• Auth lại với scope classic gồm repo (và read:org / project nếu bạn dùng các tính năng đó).
• Với GitHub Enterprise, đảm bảo gh đã xác thực với đúng hostname đó (gh auth login --hostname …).

Mạng và sự cố GitHub

Thông báo về timeout, “could not resolve host”, hoặc “GitHub is unreachable” là vấn đề kết nối:

• Kiểm tra GitHub Status.
• Thử khi tắt VPN / proxy công ty.
• Trên host remote, xác nhận HTTPS ra ngoài tới api.github.com hoạt động.

Thiếu GitHub CLI

Nếu Orca báo GitHub CLI không khả dụng:

• Cài gh.
• Xác nhận which gh chạy được trong một terminal bình thường.
• Thoát hẳn và mở lại Orca (để PATH khớp).
• Trên Windows, cài cho đúng môi trường Orca khởi chạy (WSL hay native).

Orca hành xử ra sao khi GitHub gặp sự cố

• Rate limit / outage: panel PR và Checks ưu tiên trạng thái đã biết gần nhất cộng một banner ngắn thay vì xoá sạch UI.
• Auth / quyền thất bại nặng: Bạn sẽ nhận được text empty-state hoặc banner rõ ràng hướng dẫn sửa login hoặc quyền truy cập.
• Circuit breaker: Sau một lỗi 403 rate-limit chính, Orca tạm thời từ chối tạo thêm lệnh gọi gh mới cho bucket đó (core, search, hoặc graphql) để app luôn phản hồi và không đào sâu thêm vấn đề.

Kiểm tra GitHub API Budget trong Orca

Mở Settings → Git và tìm GitHub API Budget:

• Số còn lại REST / Search / GraphQL từ probe của GitHub.
• Refresh sau khi chờ hết một giới hạn.
• Trên Orca server remote, dùng view budget nâng cao remote cho danh tính gh do server sở hữu (Settings local chỉ hiện client desktop).

Vẫn kẹt?

• Tái hiện một lần trong terminal bằng gh pr view hoặc gh api user trên cùng máy/user Orca dùng.
• Thu thập log: Help → Open Logs.
• Báo issue kèm text lỗi đã phân loại (không kèm secret), output gh auth status đã che bớt, và liệu gh trong terminal có fail giống vậy không.
• GitHub Issues
• Discord

Liên quan

• Hosted reviews, issues & Actions - tính năng PR và Checks phụ thuộc vào GitHub.
• Tài liệu tra cứu Settings - pane Integrations và Git.
• Usage & rate-limit tracking - giới hạn provider AI (Claude/Codex), không phải API GitHub.
• Xử lý sự cố & FAQ - vấn đề Orca chung.

Nguồn

Dịch và biên soạn từ trang Troubleshooting GitHub errors trong tài liệu chính thức của Orca ADE (onorca.dev).