Thiết lập tích hợp GitHub

Hướng dẫn này đề cập đến những phần dành riêng cho GitHub trong quá trình thiết lập. GitHub là một trong ba máy chủ mã được hỗ trợ — xem Kết nối máy chủ mã để kết nối GitLab hoặc Bitbucket, và để biết cách một không gian làm việc dùng chung cả ba.

Trước khi bắt đầu

Một tài khoản GitHub có quyền truy cập vào những kho mã bạn muốn làm việc
Hoặc một GitHub App đã được đăng ký cho máy chủ của bạn (xem Tạo GitHub App) để bạn có thể đăng nhập, hoặc một token truy cập cá nhân có repo và read:org để dán

Đăng nhập với GitHub

Một luồng thiết bị: GitHub hiển thị cho bạn một mã ngắn, bạn phê duyệt nó trên github.com, và máy chủ nhận thông tin xác thực — không có URL callback, không có cổng, không có gì phải mở ra ngoài. Khả dụng bất cứ khi nào máy chủ có id client, thứ mà một bản dựng chính thức đã kèm sẵn.

Mở Cài đặt → Không gian làm việc → Hồ sơ & danh tính → Lưu trữ mã (hoặc bước đầu tiên của quá trình thiết lập ban đầu)
Trên hàng GitHub, nhấn Đăng nhập với GitHub
Một hộp thoại hiển thị mã gồm tám ký tự và mở github.com/login/device trong trình duyệt của bạn. Mã đã có sẵn trong clipboard của bạn
Dán mã, phê duyệt ứng dụng, rồi quay lại. Hàng đó tự chuyển sang “Đã đăng nhập với tên your-username”

Bạn có thể đóng hộp thoại trong lúc hoàn tất thao tác trong trình duyệt — máy chủ vẫn thăm dò cho đến khi mã hết hạn (khoảng 15 phút), nên việc đăng nhập vẫn thành công.

Hoặc dán một token

Phương án dự phòng khi máy chủ không có ứng dụng, khi ứng dụng không được cài trên một tài khoản bạn cần, hoặc khi bạn đơn giản là muốn dùng PAT.

Mở Cài đặt → Không gian làm việc → Hồ sơ & danh tính → Lưu trữ mã
Trên hàng GitHub, nhấn Thêm token
Dán một token có repo và read:org (loại Classic) rồi lưu. Một token fine-grained cần quyền kho mã Contents và Pull requests (đọc và ghi), cùng Checks và Actions (đọc).

Token được kiểm tra ngay khi được lưu, nên hàng đó có thể nêu tên tài khoản mà nó thuộc về. Nhấn Ngắt kết nối để gỡ nó.

Điểm kiểm tra: hàng GitHub ghi “Đã đăng nhập với tên your-username”. Một hậu tố nêu rõ nguồn khi thông tin xác thực đang trả lời không phải của bạn — “qua ứng dụng của máy chủ này” hoặc “từ môi trường”.

Tích hợp này mang lại cho bạn những gì

Tính năng	Cách hoạt động
Danh sách và chi tiết PR	API REST của GitHub, từ máy chủ, dưới danh tính ứng dụng hoặc thông tin xác thực của chính bạn
Các lượt chạy kiểm tra	API GitHub Checks
Xuất bản đánh giá	Một bước do người dùng xác nhận, đăng đánh giá của bạn lên PR
Đăng ký kho mã	Một bản checkout được chấp nhận nếu remote `origin` của nó trỏ tới github.com — hoặc tới gitlab.com / bitbucket.org
Quyền truy cập GitHub của agent	Trình môi giới thông tin xác thực chèn một token chỉ đọc dưới dạng `GH_TOKEN` / `GITHUB_TOKEN`; push đi qua Control Center
Tín hiệu thông báo	Một lượt thăm dò phía máy chủ vào hộp thư thông báo GitHub của bạn tạo ra “Được nhắc trong pull request” và “Đã yêu cầu review”
Hồ sơ người dùng	Thẻ hồ sơ khi rê chuột và lọc PR theo từng tác giả

Một số đường đi dùng API GraphQL thay vì REST khi rẻ hơn — hoạt động của nhánh cho trình chọn soạn PR và trạng thái đánh giá trực tiếp, thứ quyết định liệu một thông báo yêu cầu đánh giá còn đang chờ hay không.

Theo dõi sự cố GitHub

Thanh tiêu đề hiển thị một chip trạng thái khi một nhà cung cấp đang gặp sự cố, bao gồm GitHub, Claude, OpenAI và Kimi. Nó bị ẩn khi mọi thứ đều bình thường — sự xuất hiện báo hiệu có trục trặc, chứ không phải sự vắng mặt của nó.

Nhấn vào chip để mở một khung bật lên hiển thị trạng thái của từng nhà cung cấp cùng nút làm mới. Các trạng thái tự làm mới sau mỗi hai phút.

Cách agent hành động trên GitHub

Một agent làm việc trong worktree GitHub luôn nhận token GitHub chỉ đọc. Một lần push đi qua Control Center, nơi hỏi quy tắc Push lên remote rồi chuyển tiếp nó bằng một token ghi mà agent không bao giờ nắm giữ. Xem Cấu hình chính sách sandbox
Các commit do agent tạo được ghi là do agent — tên hiển thị cộng thêm (agent), tại một địa chỉ tổng hợp được đánh khóa theo id của agent — không bao giờ là con người. Người đã yêu cầu được ghi công bằng một trailer Co-Authored-By
Khi đã cấu hình GitHub App, trình môi giới tạo ra các token cài đặt fine-grained, giới hạn theo kho mã và kéo dài khoảng một giờ, cho mỗi lần chạy thay vì đưa ra một token rộng. Bản cài đặt được phân giải từ owner kho mã của lượt chạy, nên một ứng dụng cài trên nhiều tài khoản sẽ giới hạn đúng theo tài khoản mà lượt chạy chạm tới. Không có ứng dụng, agent nhận token của môi trường, thứ không thể thu hẹp thành chỉ đọc: khi đó quy tắc push ràng buộc git push, nhưng không ràng buộc mã dùng trực tiếp token
Token luôn thuộc về trình môi giới, không bao giờ là token riêng của thành viên yêu cầu. Token của máy chủ bị giữ lại khỏi một lượt chạy hành động thay một thành viên không phải chủ sở hữu và chưa kết nối GitHub

Xử lý sự cố

Danh sách PR trống và báo rằng GitHub chưa được kết nối

Bạn không có thông tin xác thực GitHub nào trên máy chủ này. Hãy đăng nhập hoặc dán token trong Lưu trữ mã. Các kho mã trên những forge khác không bị ảnh hưởng — chỉ kho mã của GitHub không đóng góp gì.

Hàng đó chỉ có “Thêm token” mà không có “Đăng nhập với GitHub”

Máy chủ không có id client — đây là trạng thái bình thường đối với bản dựng từ mã nguồn, vì thông tin xác thực chỉ được nhúng vào các bản dựng chính thức. Xem Tạo GitHub App: việc này mất khoảng hai phút và chỉ chủ máy chủ phải làm, một lần.

Hộp thoại đăng nhập báo nhà cung cấp không trả về mã thiết bị

GitHub App tồn tại nhưng hộp kiểm Device flow của nó đang tắt. Hãy bật nó trong phần cài đặt của ứng dụng (General → Device flow) rồi thử lại.

Hàng đó ghi “qua ứng dụng của máy chủ này” trong khi tôi mong đợi tài khoản của mình

Bạn chưa đăng nhập; thứ bạn đang thấy là danh tính ứng dụng của máy chủ đang trả lời. Hãy nhấn Đăng nhập với GitHub trên hàng đó.

Một PAT fine-grained không hiển thị nút merge hay trạng thái kiểm tra

Token cần Contents và Pull requests (đọc và ghi), cùng Checks và Actions (đọc). Sau khi thay đổi nó, hãy dán lại trong Lưu trữ mã.

Việc thêm kho mã bị từ chối

Việc đăng ký cần cả ba điều kiện: đường dẫn nằm trong một worktree git, nó có remote origin, và remote đó trỏ tới một forge được hỗ trợ (github.com, gitlab.com hoặc bitbucket.org). Xem Thêm kho mã vào không gian làm việc.

Mọi thứ ngừng hoạt động một lúc sau khi dùng nhiều

Đó là cầu dao ngắt mạch của giới hạn tốc độ. GitHub báo hiệu giới hạn chính của nó bằng một 403 mang theo x-ratelimit-remaining: 0 và một thời điểm đặt lại; khi thấy một phản hồi như vậy, máy khách cho các yêu cầu tiếp theo thất bại ngay tại chỗ mà không gọi mạng cho đến khi hết cửa sổ thời gian, nhờ vậy một cơn bão thử lại không thể làm giới hạn sâu thêm. Các lỗi tạm thời được thử lại tối đa ba lần với backoff lũy thừa, tôn trọng retry-after.