Kết nối GitHub (GitHub App)
GitHub App của PhillipCLI nối tổ chức GitHub của bạn với tổ chức PhillipCLI. Bạn cài một lần, và nó làm ba việc:
- Tự vào. Thành viên của tổ chức GitHub đăng nhập bằng GitHub là vào tổ chức PhillipCLI, với role bạn chọn.
- Repo. Tara liệt kê các repo bạn cấp cho app. Một repo chỉ tính là của bạn khi nó nằm trong installation.
- Issue và PR. Ryoma và Bandum đồng bộ task, PR bằng token chỉ đọc, sống ngắn, do Tara xin từ GitHub. Không ai phải dán token cá nhân.
App chỉ đọc. Nó xin quyền đọc Contents, Issues, Pull requests, Metadata, và quyền đọc danh sách thành viên của tổ chức.
Ai kết nối được
Bạn cần đủ cả hai điều kiện:
- Bạn là Owner hoặc Admin của tổ chức PhillipCLI.
- Bạn là owner của tổ chức GitHub (hoặc chính tài khoản GitHub đó, nếu cài lên tài khoản cá nhân). GitHub cũng hiện installation cho thành viên thường, nên Tara kiểm tra bạn có đúng là chủ tài khoản không.
Một installation chỉ nối với một tổ chức PhillipCLI, và một tổ chức PhillipCLI chỉ nối với một installation.
Cài app
- Trong Tara, mở Settings › Source hosts rồi bấm Connect GitHub. Trên terminal, chạy
ph org github connect. - Trên GitHub, chọn tài khoản cần cài. Chọn All repositories hoặc Only select repositories.
- Bấm Install & Authorize. GitHub cũng hỏi bạn có cấp quyền cho app không. Tara dùng bước này để xác nhận bạn là ai.
- GitHub đưa bạn về Tara, trang hiện tài khoản, danh sách repo và cài đặt tự vào.
Link cài có hiệu lực 15 phút và chỉ dùng được bởi người bấm Connect. Chờ quá lâu thì bạn bắt đầu lại.
Muốn thêm hay bớt repo về sau, bạn đổi phạm vi repo của app trên GitHub. Tara cập nhật khi GitHub báo thay đổi, hoặc bạn bấm Sync now (ph org github sync).
Cho mọi người tự vào
Ở mục Auto-join, bạn chọn ai được vào khi đăng nhập bằng GitHub.
| Cài đặt | Điều xảy ra |
|---|---|
| Off (mặc định) | Không ai tự vào. Bạn tự mời. |
| Viewer | Thành viên tổ chức GitHub vào với role Viewer. Viewer miễn phí, không tốn seat. |
| Member | Họ vào với role Member và tốn một seat. |
Tự vào chỉ dùng được khi app cài trên một tổ chức GitHub, và không bao giờ cấp Admin hay Owner. Đổi bằng ph org github auto-join off|viewer|member.
- Hết seat thì đăng nhập vẫn được. Người đó nằm trong danh sách bị bỏ qua ở trang GitHub, bạn giải phóng seat hoặc mời họ.
- Ai rời tổ chức GitHub thì mất quyền vào tổ chức PhillipCLI, nhưng chỉ khi họ vào bằng cách này. Owner, người được mời và người bạn thêm tay vẫn ở lại.
- Admin gỡ một người, hoặc người đó tự rời, thì tự vào không đưa họ về lại. Muốn đảo lại, bạn mời họ lần nữa.
- Khi ngắt kết nối, những người vào bằng cách này thành thành viên bình thường.
Tara đọc danh sách thành viên từ bản sao của chính nó. Bản sao cập nhật khi GitHub báo thay đổi, mỗi giờ một lần, và khi bạn bấm Sync now. Mỗi lượt vào và gỡ đều ghi vào nhật ký audit.
Repo, task và PR trong Ryoma, Bandum
Kết nối xong, bạn thêm repo vào dự án (ph project edit <key> --add-repo owner/repo). Ryoma và Bandum đọc issue và PR của dự án đó qua installation. Chỉ repo nằm trong installation mới dùng được. Với repo ngoài installation, Tara từ chối cấp token.
Token sống khoảng một giờ, chỉ phủ các repo được xin và đều được ghi log. Token cá nhân của thành viên không xin được. Chỉ dịch vụ (Ryoma, Bandum) và Owner hoặc Admin xin được.
Kết nối từ terminal
ph org github # trạng thái, role tự vào, repo, người bị bỏ qua
ph org github connect # in địa chỉ cài và mở nó
ph org github auto-join member # off, viewer hoặc member
ph org github sync # làm mới repo và thành viên ngay
ph org github unlink --yes # ngắt kết nốiKhi gặp lỗi
| Mã | Ý nghĩa và cách xử lý |
|---|---|
installation_not_accessible | Tài khoản GitHub của bạn không thấy installation đó. Đăng nhập GitHub bằng tài khoản được cài app lên tổ chức. |
not_account_owner | Chỉ owner của tổ chức GitHub mới kết nối được. Nhờ một owner làm bước cài. |
repo_not_in_installation | Repo không nằm trong installation. Thêm repo vào phạm vi của app trên GitHub rồi đồng bộ. |
github_not_linked | Tổ chức này chưa có installation. Kết nối GitHub trước. |
installation_suspended | Installation đang bị tạm ngưng trên GitHub. Bỏ tạm ngưng trong phần GitHub Apps ở cài đặt của tổ chức GitHub. |
bad_state | Link cài đã hết hạn hoặc là của người khác. Bắt đầu lại từ Connect GitHub. |
installation_bound | Installation đó đã nối với một tổ chức PhillipCLI khác. |
org_already_linked | Tổ chức này đã kết nối rồi. Ngắt kết nối trước. |