Tạo GitHub App

Hướng dẫn này cho bạn biết cách cấp cho máy chủ của mình một danh tính GitHub riêng. Việc này mất khoảng hai phút, chỉ chủ sở hữu máy chủ thực hiện, và chỉ phải làm một lần cho mỗi máy chủ.

Để kết nối tài khoản của chính bạn sau đó, xem Thiết lập tích hợp GitHub.

Vì sao máy chủ của bạn cần ứng dụng riêng

Một lần đăng ký tạo ra hai công việc khác nhau, và chính ứng dụng là thứ khiến cả hai trung thực:

Công việc	Thứ trả lời nó	Vì sao quan trọng
Một người đăng nhập	Id client của ứng dụng, qua luồng thiết bị	Bạn có thông tin xác thực thuộc về mình, trên máy chủ, trên mọi thiết bị — không có mã thông báo nào phải dán hay xoay vòng
Máy chủ hành động	Id ứng dụng + khóa riêng → mã thông báo cài đặt	Webhook, thăm dò PR và đồng bộ phiếu không còn phụ thuộc vào việc mã thông báo của một con người vẫn còn hiệu lực

Lưu ý thứ không có trong bảng đó: bí mật client. Luồng thiết bị của GitHub chỉ xác thực bằng id client — cả yêu cầu mã thiết bị lẫn thăm dò mã thông báo — nên không có bí mật nào phải giữ để đăng nhập.

Không có ứng dụng riêng, việc thứ nhất vẫn hoạt động nhờ id client mà bản dựng kèm sẵn; việc thứ hai chuyển sang dùng thông tin xác thực của chủ sở hữu máy chủ, nên công việc nền dựa vào người thiết lập đầu tiên.

Điều kiện tiên quyết

Bạn là chủ sở hữu máy chủ — các thao tác providerApps.* chỉ dành cho vai trò đó, và những người khác không nhìn thấy thẻ này
Một tài khoản GitHub, hoặc một tổ chức mà bạn có thể tạo ứng dụng trong đó
Không cần gì truy cập được từ công khai: đăng nhập dùng luồng thiết bị, nên máy chủ không cần cổng vào, tunnel, URL callback hay tên miền nào

Đăng ký ứng dụng

Mở github.com/settings/apps/new (với tổ chức: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — gì cũng được; Control Center (yourname) là ổn. Tên này hiện trên các commit và bình luận mà máy chủ tạo
Homepage URL — gì cũng được, ví dụ https://github.com/your-name
Callback URL — để trống. Luồng thiết bị không dùng nó
Tích Enable Device Flow. Đây là thiết lập duy nhất mà đăng nhập không thể hoạt động nếu thiếu
Bỏ tích Webhook → Active trừ khi bạn nối webhook riêng
Trong Repository permissions, cấp ít nhất:
- Contents: Read and write
- Metadata: Read-only (bắt buộc)
- Pull requests: Read and write
- Issues: Read and write, nếu bạn dùng GitHub Issues cho phiếu, và cho việc bot tìm bình luận trong hội thoại PR (xem Nói chuyện với Control Center từ một PR GitHub)
- Checks: Read-only, để hiển thị trạng thái CI trên trang PR
Trong Where can this GitHub App be installed?, chọn cái nào phù hợp — “Only on this account” là đúng cho máy chủ cá nhân
Nhấn Create GitHub App

Thu thập ba giá trị

Trên trang của ứng dụng, ngay sau khi tạo:

Giá trị	Ở đâu
App ID	Tab General, gần phía trên
Client ID	Tab General, dưới “Client secrets”
Private key	Generate a private key — một tệp `.pem` được tải xuống

Tệp khóa riêng chỉ tải xuống một lần và GitHub không bao giờ hiển thị lại. Hãy giữ nó cho đến khi bạn đã dán; bạn luôn có thể tạo một cái khác.

Bí mật client là tùy chọn và chỉ mang lại đúng một thứ: nếu bạn để “Expire user authorization tokens” BẬT, nó là thứ âm thầm gia hạn mã thông báo của một người thay vì yêu cầu họ đăng nhập lại sau mỗi tám giờ. Bản thân việc đăng nhập không bao giờ dùng nó.

Thiết lập đơn giản hơn là TẮT thời hạn đó, và khi đó không cần bí mật nào ở đâu cả. Nếu bạn giữ nó bật, hãy tạo một bí mật và dán vào Cài đặt → Máy chủ → Đăng nhập một lần (thẻ Ứng dụng nhà cung cấp) — không có biến môi trường nào cho nó, và cũng không có biến nào được nhúng vào bản dựng, nên nó ở lại trên máy chủ của bạn.

Cài đặt nó trên tài khoản của bạn

Một ứng dụng đã đăng ký nhưng chưa cài đặt có thể xác thực người dùng và không đọc được gì.

Trên trang của ứng dụng, mở Install App
Cài đặt nó trên tài khoản hoặc tổ chức của bạn
Chọn All repositories, hoặc chọn những kho mã mà máy chủ này nên thấy

Dán nó vào Control Center

Vào Cài đặt → Máy chủ → Đăng nhập một lần và cuộn tới thẻ Ứng dụng nhà cung cấp
Trên khối GitHub, đặt từng trường:
- Id ứng dụng — App ID dạng số
- Khóa riêng — dán toàn bộ tệp .pem, kể cả các dòng BEGIN và END
- Id client — từ cùng trang đó
- Bí mật client — chỉ khi bạn đã tạo một cái (để gia hạn mã thông báo)
Nhấn Kiểm thử

Khóa được phân tích ngay khi lưu, nên một lần dán bị cắt cụt hay sai định dạng sẽ bị từ chối ngay tại đó thay vì thất bại trên một yêu cầu nền hàng giờ sau. Kiểm thử đi xa hơn và hỏi GitHub xem ứng dụng đã được cài trên những tài khoản nào — “đã lưu” và “hoạt động” là hai khẳng định khác nhau, và chỉ khẳng định thứ hai mới có nghĩa là sẽ có gì đó chạy.

Điểm kiểm tra: khối GitHub hiển thị “Máy chủ có thể hành động với tư cách của chính nó, và mọi người có thể đăng nhập.”, và hàng GitHub trong Cài đặt → Không gian làm việc → Hồ sơ & danh tính → Lưu trữ mã giờ đây có Đăng nhập với GitHub.

Cấu hình bằng biến môi trường thay thế

Với bản cài không giao diện hoặc chạy bằng script, máy chủ nạp mỗi trường từ môi trường trong lần đầu nó không có giá trị nào được lưu:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

Không có cờ dòng lệnh nào cho những giá trị này — một bí mật trên dòng lệnh thì mọi tiến trình trên máy chủ đều đọc được qua ps. Môi trường là nơi duy nhất để cấu hình chúng, và nó thắng bất kể thứ gì bản dựng kèm theo. .env.template là danh sách đầy đủ.

Khi phát triển cục bộ, tệp .env ở gốc kho mã mang cùng các giá trị đó và ứng dụng desktop truyền chúng cho máy chủ mà nó khởi chạy. Hãy đặt khóa trên một dòng ở đó: một giá trị .env là một dòng, và \n bên trong dấu ngoặc kép được giải mã thành ký tự xuống dòng.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID và GITHUB_APP_PRIVATE_KEY là cùng những tên mà trình môi giới mã thông báo của sandbox vốn đã đọc, nên một máy chủ đã cấu hình mã thông báo agent chi tiết sẽ có sẵn làn đăng nhập. Việc nạp diễn ra một lần cho mỗi trường — sau đó giá trị đã lưu thắng, nên chỉnh sửa trong Cài đặt không bị lần khởi động lại kế tiếp hoàn tác.

Làm điều tương tự với Linear

Linear không có luồng thiết bị, nên đăng nhập của nó là một vòng qua trình duyệt và nó thực sự cần URL callback — thẻ Ứng dụng nhà cung cấp cho bạn thấy chính xác URL cần đăng ký.

Tạo một ứng dụng OAuth tại linear.app/settings/api/applications/new
Đặt Callback URL bằng URL mà thẻ hiển thị, nguyên văn
Dán Client ID và Client secret vào khối Linear
Tùy chọn thêm một khóa API của không gian làm việc — đó là thông tin xác thực mà máy chủ dùng để đồng bộ phiếu khi không có con người yêu cầu

Xử lý sự cố

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

Enable Device Flow đang tắt trên ứng dụng. Hãy bật nó trong General rồi thử lại.

Kiểm thử báo thông tin xác thực hoạt động nhưng ứng dụng không được cài ở đâu cả

Đăng ký và cài đặt là hai bước riêng biệt. Mở Install App trên trang của ứng dụng rồi cài đặt nó.

Kiểm thử báo không đọc được khóa riêng

Hãy dán toàn bộ tệp .pem, kể cả các dòng -----BEGIN và -----END. Không thể dùng khóa ed25519 hay EC — GitHub App ký bằng RSA.

Một thành viên đã đăng nhập nhưng không thấy kho mã nào

Ứng dụng chưa được cài trên tài khoản sở hữu chúng, hoặc bản cài của nó chọn những kho mã khác. Việc đăng nhập của chính họ chỉ cấp những gì ứng dụng được phép thấy.