Kết nối GitLab
Owner hoặc Admin nối được một group GitLab với tổ chức PhillipCLI. Đây là phần tương đương của GitHub App, và nó làm cùng ba việc:
- Tự vào. Thành viên của group đăng nhập bằng GitLab là vào tổ chức PhillipCLI, với role bạn chọn.
- Repo. Một repo chỉ tính là của bạn khi nó nằm trong group, kể cả subgroup. Khi bạn gõ repo cho một dự án, Tara đối chiếu với group và cảnh báo nếu repo nằm ngoài.
- Issue và merge request. Ryoma và Bandum đọc chúng bằng credential sống ngắn do Tara cấp. Không ai phải dán token cá nhân.
Mỗi tổ chức có tối đa một kết nối GitLab, và có thể có thêm GitHub App bên cạnh.
Ai kết nối được, và host nào
Bạn phải là Owner hoặc Admin của tổ chức PhillipCLI và đang đăng nhập trên Portal hoặc CLI. Token API không đổi được kết nối.
Host là https://gitlab.com, hoặc một GitLab tự dựng mà người vận hành Tara đã cho phép. Host khác bị từ chối với mã host_not_allowed. Nếu bạn chạy GitLab tự dựng mà host chưa có trong danh sách, hãy nhờ người vận hành (trang developer).
Hai cách cấp quyền cho Tara
| OAuth | Dán token | |
|---|---|---|
| Cách làm | Bạn đăng nhập GitLab, cho phép quyền đọc, rồi chọn group | Bạn dán Group Access Token, Project Access Token hoặc personal access token của một tài khoản bot, và gõ tên group |
| Cần | Người vận hành đã đăng ký OAuth application cho host đó | Không cần gì từ người vận hành |
| Scope | api (Tara cũng tạo được label) | api (hoặc read_api nếu chỉ cần đọc) |
| Khi bạn rời công ty | Kết nối phụ thuộc vào tài khoản GitLab của bạn | Vẫn chạy tiếp |
Nên dùng khi cần cô lập chặt: Group Access Token với role Reporter. Nó chỉ có phạm vi trong group, và không mất khi có người nghỉ việc. Token chỉ có read_api vẫn nối được, nhưng Tara sẽ không tạo được bộ label chuẩn (gitlab_write_required). Với OAuth, bạn chọn được tài khoản của chính mình (các dự án bạn sở hữu) hoặc group mà bạn là Maintainer trở lên. Dùng tài khoản của mình thì không có group, nên đồng đội được mời qua email thay vì tự vào.
Credential đọc được những gì
GitLab không thu hẹp được token xuống một repo, nên credential mà Tara đưa cho Bandum và Ryoma đọc được mọi thứ mà chính credential đó đọc được. Tara chỉ đưa nó cho các repo nằm trong group đã kết nối. Muốn phạm vi nhỏ, hãy dùng Group Access Token của đúng group đó.
Kết nối
- Trong Tara, mở Settings › Source hosts (trên terminal là
ph org gitlab connect). - Bấm Kết nối GitLab và cho phép. Danh sách host chỉ hiện khi máy chủ cho phép nhiều hơn một GitLab. Quản trị viên có thể mở mục Cách khác cho quản trị viên rồi dán token cùng group (hoặc tên người dùng của mình).
- Chọn nơi để dự án. Nếu chỉ một nơi có dự án thì Tara chọn giúp bạn. Chưa có dự án nào trên GitLab thì hãy tạo một dự án rồi bấm Kiểm tra lại.
- Trang hiện host, group, loại credential và cài đặt tự vào.
ph org gitlab # trạng thái
ph org gitlab connect --host https://gitlab.com # OAuth trên trình duyệt, rồi chọn group
ph org gitlab connect --token-stdin --group acme/platform < token.txt
ph org gitlab group acme/platform # chọn group cho kết nối đang chờ
ph org gitlab auto-join member # off, viewer hoặc member
ph org gitlab sync # đối chiếu thành viên ngay
ph org gitlab webhook --rotate # tạo secret webhook, chỉ hiện một lần
ph org gitlab unlink --yes # ngắt kết nốiToken được đọc từ đầu vào chuẩn, không bao giờ từ tham số dòng lệnh, và Tara lưu nó đã mã hóa. Nếu máy chủ chưa cấu hình khóa mã hóa, trang sẽ báo chưa kết nối GitLab được và người vận hành cần đặt khóa.
Cho mọi người tự vào
| Cài đặt | Chuyện gì xảy ra |
|---|---|
| Off (mặc định) | Không ai tự vào. Bạn mời người. |
| Viewer | Thành viên group vào làm Viewer, miễn phí và không chiếm seat. |
| Member | Họ vào làm Member và chiếm một seat. |
Luật giống GitHub. Tự vào không bao giờ cấp Admin hay Owner. Khi hết seat (gói Free có bảy), đăng nhập vẫn được và người đó được ghi vào danh sách bị bỏ qua. Ai rời group thì bị gỡ, nhưng chỉ khi họ vào bằng cách này. Người mà Admin đã gỡ sẽ không tự quay lại.
Một người chỉ khớp khi họ đăng nhập Tara bằng GitLab trên cùng host với kết nối. Việc đó cần máy chủ Tara có đăng nhập GitLab cho host ấy (người vận hành cài bằng TARA_GITLAB_PROVIDERS; gitlab.com làm nguồn đăng nhập là một phần tử riêng, khác phần tử chỉ để kết nối). Tara hỏi GitLab bằng credential của kết nối xem người đó có trong group không. Mỗi lần vào và gỡ đều có trong nhật ký kiểm toán.
Webhook (tùy chọn)
Không có webhook thì Tara vẫn đối chiếu thành viên và đồng bộ nguồn knowledge mỗi giờ. Webhook chỉ giúp Tara phản ứng ngay. Tara không tự tạo hook được, nên bạn thêm bằng tay:
- Trong Tara, ở mục Webhook, bấm Create or rotate secret. Chép secret ngay, vì nó chỉ hiện một lần. URL hiện ở cùng trang.
- Trong GitLab, thêm group webhook nếu gói của bạn cho phép (Premium, Ultimate, hoặc máy chủ tự dựng). Nếu không thì thêm webhook cho từng project.
- Dán URL, đặt secret vào Secret token, rồi tick Member events, Project events và Push events.
- Member events giữ danh sách người khớp với group. Loại này chỉ có ở group webhook.
- Push events đồng bộ một nguồn knowledge khi nhánh mặc định đổi.
- Xoay secret làm secret cũ ngừng hoạt động ngay.
Repo, task và merge request trong Ryoma và Bandum
Thêm repo vào dự án bằng URL đầy đủ, ví dụ ph project edit <key> --add-repo https://gitlab.com/acme/platform/api. Ryoma đọc owner/repo trần như repo GitHub, nên repo GitLab cần URL. Sau đó Ryoma và Bandum đọc chúng qua credential của group. Chỉ repo nằm trong group mới chạy, Tara từ chối cấp credential cho repo khác, và còn kiểm repo có tồn tại. Credential có hiệu lực tối đa một giờ, không xin được bằng token cá nhân của thành viên, và mọi lần xin đều được ghi lại.
Một lần xin có thể phủ nhiều repo của group, nên Bandum và Ryoma không cần xin riêng cho từng repo.
Khi có sự cố
| Mã | Ý nghĩa và cách xử lý |
|---|---|
host_not_allowed | Người vận hành chưa cho phép host đó. |
oauth_not_configured | Người vận hành chưa đăng ký OAuth application cho host đó. Hãy dán token. |
token_invalid | Token hết hạn, thiếu read_api, hoặc không thấy group. |
reauth_required | GitLab từ chối credential (bị thu hồi, hoặc refresh OAuth lỗi). Ngắt kết nối rồi kết nối lại. |
repo_not_in_group | Repo nằm ngoài group đã kết nối. |
org_already_linked | Tổ chức đã có kết nối GitLab. Ngắt kết nối cũ trước. |
bad_state | Link OAuth hết hạn (15 phút) hoặc là của người khác. Bắt đầu lại. |