Chuẩn bị GitHub và GitLab
Trang này dành cho người quản trị tổ chức GitHub hoặc group GitLab của công ty bạn. Bạn làm một lần trước khi mời mọi người vào tổ chức PhillipCLI. Xong các bước dưới đây, mọi người đăng nhập được Tara bằng tài khoản GitHub hoặc GitLab, Phillip kết nối được bằng một lần bấm Authorize, còn Bandum và Ryoma đọc được issue và PR của dự án.
Trên dịch vụ dùng chung của PhillipCLI
Trên dịch vụ dùng chung (tara.phillipcli.cloud), ai có tài khoản GitHub cũng đăng nhập được, và OAuth app của nền tảng đã có sẵn. Bạn không cần tự đăng ký app đăng nhập Tara. Đăng nhập chỉ cho biết bạn là ai. Muốn vào một tổ chức thì cần lời mời, gửi từ Portal hoặc bằng ph org invite. Thành viên tổ chức GitHub của bạn tự vào được nhờ GitHub App (Kết nối GitHub), và tổ chức tự cài được SSO riêng ngay trên Portal (SSO của tổ chức). Các bước tạo app đăng nhập Tara bên dưới dành cho bản tự cài. Muốn đăng ký GitHub App cho bản tự cài, xem Đăng ký GitHub App.
Ảnh GitLab trong trang chụp trên GitLab Community Edition 18.11. Bản khác có thể đặt nút ở chỗ hơi khác, nhưng tên mục vẫn giống.
| Việc | GitHub | GitLab | Ai làm |
|---|---|---|---|
| Nơi chứa người và repo | Tổ chức | Group | Owner |
| Đăng nhập Tara | OAuth app Tara | Ứng dụng Tara của group | Owner tổ chức hoặc group |
| Phillip kết nối không cần dán token | OAuth app Phillip | Ứng dụng Phillip của group | Owner tổ chức hoặc group |
| Bandum, Ryoma đọc dữ liệu | Token fine-grained chỉ đọc | Group access token read_api | Owner |
| Ryoma đồng bộ ngay khi có thay đổi (tùy chọn) | Webhook của repo | Webhook của project | Maintainer trở lên |
Tổ chức và thành viên
GitHub
Nếu chưa có tổ chức, bạn vào ảnh đại diện › Your organizations › New organization rồi chọn gói Free. Hãy chọn tên ổn định ngay từ đầu.
Để mời thành viên, bạn vào trang tổ chức › People › Invite member, gõ tên tài khoản GitHub hoặc email rồi bấm Invite. Người được mời phải chấp nhận lời mời thì mới thấy repo của tổ chức.
GitLab
Hãy dùng một group cho những người sẽ vào tổ chức PhillipCLI của bạn. Tara ánh xạ group sang vai trò trong tổ chức theo đường dẫn đầy đủ của group, ví dụ acme hoặc acme/dev. Bạn tạo group ở Groups › New group › Create group, đặt tên và chọn Private.
Để thêm người, bạn vào group › Manage › Members › Invite members, chọn tài khoản và vai trò rồi bấm Invite. Dev và Test cần vai trò Developer trở lên để mở merge request. BA chỉ cần đọc và kiểm thử thì để Reporter là đủ.
OAuth app cho đăng nhập Tara
GitHub
- Vào trang tổ chức › Settings › Developer settings › OAuth Apps › New OAuth app. Tạo app dưới tổ chức, đừng tạo dưới tài khoản cá nhân, để app không phụ thuộc vào một người.
- Điền Application name là
Tara, Homepage URL là địa chỉ Tara, Redirect URI là<địa chỉ Tara>/auth/github/callback. Không tích Enable Device Flow. - Bấm Register application, rồi bấm Generate a new client secret ở trang vừa mở. Secret chỉ hiện một lần, bạn chép ngay.
Tara xin hai quyền read:user và user:email, chỉ để đọc hồ sơ. Tara không xin read:org và không kiểm tra tư cách thành viên tổ chức, nên đăng nhập GitHub chỉ cho biết người đó là ai. Bạn đặt các biến sau cho Tara:
TARA_GITHUB_CLIENT_ID=<Client ID>
TARA_GITHUB_CLIENT_SECRET=<Client secret>Với bản tự cài một tổ chức, bạn có thể đặt thêm TARA_GITHUB_ORG để thành viên của tổ chức GitHub đó tự vào tổ chức (xem Tự cài một tổ chức). Biến này chỉ dùng cho việc đó, và chỉ khi ấy Tara mới xin thêm quyền read:org để đọc tư cách thành viên. Tổ chức GitHub nào bật Third-party application access policy ở chế độ hạn chế thì OAuth app của người ngoài phải được owner duyệt mới đọc được dữ liệu tổ chức. App do chính tổ chức sở hữu thì không bị chặn, đây là lý do bước 1 tạo app dưới tổ chức. Bạn xem chính sách ở Settings › Third-party access › OAuth application policy.
GitLab
Bạn không cần quyền admin của cả máy chủ GitLab. Owner của group tạo được ứng dụng ngay trong group.
- Vào group › Settings › Applications › Add new application.
- Điền Name là
Tara, Redirect URI là<địa chỉ Tara>/auth/gitlab/<id>/callback.<id>là mã bạn tự đặt cho máy chủ GitLab này trong cấu hình Tara, ví dụacme. - Giữ Confidential được tích, không tích Device authorization grant. Ở Scopes, tích
openid,profile,emailvàapi. Scopeapigiúp chính ứng dụng này kết nối GitLab của tổ chức bằng một cú bấm (xem bên dưới); thiếu nó thì chỉ kết nối được bằng token dán. - Bấm Save application. Trang kết quả hiện Application ID và Secret. Secret chỉ hiện đầy đủ lúc này, bạn chép ngay.
Mỗi máy chủ GitLab là một phần tử trong TARA_GITLAB_PROVIDERS. Secret nên truyền qua biến riêng:
export TARA_GITLAB_ACME_SECRET=<Secret>
export TARA_GITLAB_PROVIDERS='[
{ "id": "acme", "name": "GitLab Acme", "url": "https://gitlab.example.com",
"clientId": "<Application ID>", "clientSecretEnv": "TARA_GITLAB_ACME_SECRET",
"groups": { "acme": "member", "acme/admins": "admin", "acme/guests": "viewer" } }
]'Phần groups ánh xạ đường dẫn đầy đủ của group sang vai trò trong tổ chức: admin, member hoặc viewer. Group không cấp được owner. Người thuộc nhiều group trong danh sách thì được vai trò cao nhất. Vai trò này vào tổ chức duy nhất của bản tự cài (TARA_SINGLE_ORG). Người không thuộc group nào trong danh sách sẽ thấy thông báo nhờ trưởng nhóm thêm vào group. Nếu một giá trị không phải vai trò hợp lệ thì Tara báo lỗi ngay lúc khởi động. Bỏ trống groups thì mọi tài khoản trên GitLab đó đều đăng nhập được, giống GitHub, và không ai tự vào tổ chức nào.
Kết nối group GitLab với một tổ chức
Ngoài đăng nhập, Owner hoặc Admin của tổ chức còn kết nối được một group GitLab bằng OAuth. Để làm được, thêm vào TARA_GITLAB_PROVIDERS một phần tử có "connectOnly": true. Phần tử này chỉ dùng để kết nối tổ chức, không là nút đăng nhập, và groups được để trống:
export TARA_GITLAB_COM_SECRET=<Secret>
export TARA_GITLAB_PROVIDERS='[
{ "id": "gitlab-com", "name": "GitLab.com", "url": "https://gitlab.com", "connectOnly": true,
"clientId": "<Application ID>", "clientSecretEnv": "TARA_GITLAB_COM_SECRET" }
]'Đăng ký OAuth application trên GitLab đó (Settings › Applications của group hoặc tài khoản) với các giá trị sau:
- Redirect URI:
<TARA_PUBLIC_URL>/auth/gitlab-connect/callback, ví dụhttps://tara.example.com/auth/gitlab-connect/callback. Địa chỉ này khác callback đăng nhập ở trên. - Confidential: bật.
- Scopes:
api(đã gồm đọc và tạo label, nên nút kết nối không cần gì thêm). Ứng dụng đồng thời dùng để đăng nhập cầnopenid profile email api. - Redirect URI thứ hai (nút Kết nối GitLab một cú bấm trên Bandum):
<TARA_PUBLIC_URL>/auth/scm-user/callback, ở dòng riêng của cùng ứng dụng.
Cách làm giống nhau cho gitlab.com và GitLab tự dựng: dùng url của máy chủ đó. Tara cho phép https://gitlab.com và url của mọi phần tử trong TARA_GITLAB_PROVIDERS làm host kết nối, còn host khác bị từ chối. Host chưa có OAuth application vẫn kết nối được bằng cách dán Group Access Token. Tara lưu credential đã mã hóa, nên hãy đặt TARA_SECRET_KEY hoặc TARA_SECRETS_VAULT_*; thiếu thì trang kết nối báo chưa kết nối GitLab được. Muốn người dùng đăng nhập bằng cùng host đó, thêm một phần tử thứ hai cho host ấy, không có connectOnly.
Bandum và Ryoma đọc repo GitLab bằng credential do Tara cấp, dùng kit kit-scm-gitlab bên cạnh kit GitHub. Đặt BANDUM_SCM_GITLAB_PLUGIN (kèm BANDUM_SCM_GITLAB_PLUGIN_SHA256, hoặc BANDUM_SCM_GITLAB_PLUGIN_DIR cho bản local) và RYOMA_SCM_GITLAB_PLUGIN (name@version:sha256). Ryoma cần thêm RYOMA_SCM_PLUGIN và RYOMA_TARA_SCM_TOKEN. Với Helm chart của Ryoma, kit này là value config.scmGitlabPlugin; bản một máy (single-host) đọc cùng các biến từ file env. Mỗi repo được đọc từ host của kết nối của tổ chức, nên nhiều tổ chức có thể dùng GitHub, gitlab.com và GitLab tự dựng cùng lúc. Không có kit GitLab thì repo GitLab không được đọc.
Sau khi khởi động lại Tara, trang đăng nhập có thêm nút với tên bạn đặt ở name. Lần đầu bấm, GitLab hỏi người dùng có cho Tara đọc hồ sơ không.
OAuth app cho Phillip
Có app này thì ph connect mở trình duyệt để người dùng bấm Authorize, không phải tự tạo token. App này là app public, không có secret, vì nó chạy trên máy từng người.
GitHub
Bạn tạo thêm một OAuth app dưới tổ chức như ở trên, với Application name là Phillip, Redirect URI là http://127.0.0.1:7171/callback, và tích Enable Device Flow. Device flow cho phép người dùng trên máy không mở được trình duyệt nhập mã ở github.com/login/device. App này không cần client secret.
GitLab
Trong group › Settings › Applications, bạn tạo ứng dụng Phillip với Redirect URI là http://127.0.0.1:7171/callback, bỏ tích Confidential, và chỉ tích scope api.
Device flow trên GitLab 18 đang tắt mặc định (feature flag oauth2_device_grant_flow). Vì vậy với GitLab, bạn đặt deviceFlow là false, Phillip sẽ mở trình duyệt thay vì đưa mã.
Khai báo cả hai app cho Tara để Tara phát lại cho Phillip:
TARA_SCM_OAUTH_CLIENTS='[
{ "host": "github.com", "kind": "github", "clientId": "<Client ID app Phillip>", "deviceFlow": true, "scopes": ["repo"] },
{ "host": "gitlab.example.com", "kind": "gitlab", "clientId": "<Application ID app Phillip>", "deviceFlow": false,
"redirectPort": 7171, "scopes": ["api"] },
{ "host": "localhost:8929", "scheme": "http", "kind": "gitlab", "clientId": "<Application ID app Phillip>",
"redirectPort": 7171, "scopes": ["api"] }
]'host là tên máy chủ, kèm :cổng khi máy chủ không chạy ở cổng mặc định (như localhost:8929), không có https:// hay đường dẫn. scheme là tùy chọn (http hoặc https, mặc định https); máy chủ tự dựng không có TLS thì ghi "scheme": "http". Đây là app public nên trong JSON không được có secret, có secret thì Tara báo lỗi lúc khởi động.
Token dịch vụ cho Bandum và Ryoma
Bandum online và Ryoma đọc issue, PR và file kiểm thử bằng một token chỉ đọc của tổ chức, không dùng token của người nào. Kết quả kiểm thử tay vẫn ghi dưới tên người bấm, bằng token của chính họ.
GitHub
Bạn dùng một tài khoản dịch vụ là thành viên của tổ chức, vào Settings › Developer settings › Personal access tokens › Fine-grained tokens › Generate new token. Chọn Resource owner là tổ chức và Only select repositories với các repo dự án.
Ở Permissions, bấm Add permissions rồi thêm Contents, Issues, Pull requests. Với token dịch vụ, bạn để cả ba ở Read-only. Metadata luôn ở Read-only và không bỏ được. Ảnh dưới là token cá nhân của Dev nên đặt Read and write.
Nếu tổ chức bật duyệt fine-grained token, token chỉ dùng được sau khi owner duyệt ở Settings › Personal access tokens › Pending requests.
GitLab
Bạn dùng group access token, không cần tài khoản dịch vụ. Vào group › Settings › Access tokens › Add new token, đặt tên ví dụ bandum-ryoma-doc, chọn hạn dùng, vai trò Reporter và chỉ tích read_api.
Token có hạn dùng tối đa một năm. Bạn đặt nhắc lịch để cấp token mới trước khi hết hạn, vì hết hạn thì Bandum và Ryoma ngừng đồng bộ.
Đặt token vào cấu hình dịch vụ:
BANDUM_SCM_PLUGIN=kit-scm-gitlab@<version> BANDUM_SCM_PLUGIN_SHA256=<sha256> BANDUM_SCM_TOKEN=<token>
RYOMA_SCM_PLUGIN=kit-scm-gitlab@<version>:<sha256> RYOMA_SCM_TOKEN=<token>Với GitLab tự dựng, bạn thêm BANDUM_SCM_SETTINGS và RYOMA_SCM_SETTINGS là {"apiUrl":"https://gitlab.example.com/api/v4","webUrl":"https://gitlab.example.com"}, vì kit mặc định gọi gitlab.com. apiUrl là địa chỉ API mà dịch vụ gọi. webUrl là địa chỉ trang web, Bandum dùng nó cho link Create token (tạo token) để người dùng mở đúng trang tạo token của máy chủ bạn. Quên webUrl thì link vẫn trỏ về gitlab.com, và Bandum ghi cảnh báo lúc khởi động. Máy cá nhân dùng Phillip thì đặt PHILLIP_GITLAB_URL (và PHILLIP_GITLAB_API nếu cần) cho cùng mục đích; GitHub Enterprise có PHILLIP_GITHUB_URL. Version và sha256 của kit lấy ở trang tài nguyên trên Tara.
Webhook cho Ryoma
Không có webhook, Ryoma vẫn đồng bộ theo chu kỳ (mặc định 5 phút). Webhook chỉ giúp số liệu cập nhật gần như ngay. Ryoma không đọc nội dung webhook, nó chỉ đánh dấu repo cần đồng bộ rồi đọc lại qua token dịch vụ.
Bạn đặt một bí mật chung bằng RYOMA_WEBHOOK_SECRET (ví dụ sinh bằng openssl rand -hex 32), rồi tạo webhook với URL <địa chỉ Ryoma>/webhooks/scm?repo=<URL repo>.
Trên GitHub, bạn vào repo › Settings › Webhooks › Add webhook. Chọn Content type là application/json, dán bí mật vào Secret, chọn Let me select individual events rồi tích Issues và Pull requests. GitHub ký nội dung bằng bí mật đó, Ryoma kiểm chữ ký.
Trên GitLab, bạn vào project › Settings › Webhooks › Add new webhook. Dán bí mật vào Secret token, tích Work item events (trước đây tên là Issues events) và Merge request events.
Kiểm tra lại
- Mở trang đăng nhập Tara, thấy đủ nút GitHub hoặc GitLab đã cấu hình. Đăng nhập thử bằng một tài khoản thành viên. Trên dịch vụ dùng chung hay bản nhiều tổ chức, người chưa có tổ chức sẽ thấy màn hình Get started. Trên bản dùng GitLab hoặc SSO, tài khoản ngoài các group đã ánh xạ bị chặn kèm lời nhắc.
- Trên một máy Dev, chạy
ph connecttrong repo dự án. Trình duyệt mở ra màn hình Authorize, không hỏi dán token. - Trên Bandum, bấm Sync now (đồng bộ ngay) ở Board và thấy issue của sprint hiện tại.
- Sửa label một issue rồi xem Ryoma cập nhật trong vài giây nếu đã bật webhook.
Thành viên làm phần của mình theo Kết nối GitHub hoặc GitLab.