Chuyển tới nội dung chính

Tạo Space và quản thành viên

Với quyền owner có được sau bước bootstrap lần đầu, trang này hướng dẫn tạo Space mới qua provisioning, chọn chiến lược hợp nhất và mời thành viên theo đúng role.

Đối tượng: chủ dự án — người mở Space, gắn repo, mời team, cấp cứu khi mất quyền admin. Role kỹ thuật: Board owner (rank cao nhất). Người tạo Space tự thành owner. Nguyên tắc gán quyền: cấp tối thiểu đủ dùng — viewer (xem) · member (làm) · admin (duyệt) · owner (chỉ chủ dự án).

Công cụ bạn dùng​

Công cụBạn làm gì
Trang Projects → New Project / Edit / DeleteTạo Space, sửa cấu hình, xoá Space
GET /api/spaces/<spaceId>/members + POST/DELETEXem, thêm/đổi role, xoá thành viên
Biến AGENTBOARD_BOOTSTRAP_OWNERS trên server + restartKhởi tạo lần đầu và break-glass khi mất hết admin
Board / Tree / Review ViewGiám sát chung (đọc như viewer, duyệt như admin khi cần)

Lần đầu khởi tạo quyền quản trị​

Áp dụng ngay sau deploy đầu tiên, khi DB mới hoàn toàn và phân quyền fail-closed (chưa ai có quyền gì). Chi tiết từng bước: Bài 1 — Lần đầu đăng nhập.

  1. Mở URL production, qua SSO. Danh sách Space trống, mọi hành động 403 — đúng thiết kế.
  2. Trên server (/opt/agentjira/.env): AGENTBOARD_BOOTSTRAP_OWNERS=lead@yourcompany.com → restart agentjira_server → xác nhận log [rbac] applied 1 bootstrap owner grant(s).
  3. Refresh UI → bạn là owner mọi Space hiện có.

Lệnh grant idempotent — vừa là đường khởi tạo lần đầu, vừa là đường break-glass khi mất hết admin.

Môi trường dev

DEV-LITE không cần bước này (AGENTBOARD_DEV_IDENTITY=1 cho mọi request làm owner). DEV FULL-STACK chạy y production (DEV_USER_EMAIL đưa vào bootstrap).

Tạo Space mới — provisioning 2-phase bù trừ​

  1. New Project, điền:
    • name; repoPath (đường dẫn tuyệt đối tới repo git) hoặc repoUrl (server tự clone vào cloneRoot);
    • defaultAgentType, defaultBaseBranch (thường main);
    • defaultUseWorktree — bật (khuyến nghị mạnh);
    • requireHumanGate — bật để cưỡng chế chốt người;
    • mergeStrategy — xem 3 tab dưới.
  2. Submit → server provisioning 2-phase: tạo Space trong Board DB trước → tạo Department bên Arkon → sinh Wiki Home (slug: home) → tạo đúng 5 persona (architect, coder, reviewer, qa, devops, mỗi persona một Arkon Employee + MCP token mã hoá at-rest) → lưu link Space↔Department → cấp bạn làm owner.
  3. Nếu Arkon lỗi giữa đường: bù trừ ngược — xoá Department dở dang + link + Space vừa tạo, không để rác. Nếu Arkon không sống: Space vẫn tạo thành công kèm cờ degraded, chỉ ghi console.warn trên server (không có Activity Space-level — bảng activities bắt buộc task_id tham chiếu tasks, nên sự kiện cấp Space không ghi được vào đó) (suy biến mềm).
  4. Xác minh: Board mới có 2 tab Board + Wiki; bên Arkon :3119 → Departments thấy tên Space với trang Home.

Ba chiến lược hợp nhất (mergeStrategy)​

Chiếm mutex withRepoLock → git merge --no-ff nhánh agent vào baseBranch → task done. Mặc định — dùng khi repo và server cùng host.

Quyết định lúc tạo, đổi sau cần cân nhắc — ghi lại mergeStrategy + requireHumanGate

của từng Space và lý do chọn.

Chi tiết API đã kiểm chứng với code (POST /api/projects không đòi membership — Space chưa tồn tại thì chưa thể đòi; người tạo tự thành owner):

  • Body nhận: name (bắt buộc nếu không đưa repoPath/repoUrl), repoPath phải tuyệt đối, repoUrl hoặc repoPath (đưa cả hai → 400 provide either repoUrl or repoPath, not both), defaultAgentType, defaultPriority, defaultBaseBranch, defaultUseWorktree, requireHumanGate (boolean, mặc định false khi không đưa), mergeStrategy (merge-local mặc định | create-pr | manual, sai giá trị → 400).
  • isDefault là bất biến — đưa vào body → 400.
  • Sửa cấu hình sau này (PATCH /api/projects/:id) và xoá Space (DELETE, Space default không xoá được → 409) đòi role owner của đúng Space đó.
  • Đổi repoPath sau khi đã có task/group → 409.

Mời thành viên & phân quyền​

NgườiRoleVì sao
PO, StakeholderviewerXem tiến độ, không tạo/sửa
DevelopermemberTạo task, chạy agent, apply plan — nhưng không approve
Tech Lead, RevieweradminĐược approve & merge (Human Gate)
Chủ dự ánownerSửa cấu hình Space, quản lý thành viên
# Xem danh sách
curl http://<host>/api/spaces/<spaceId>/members

# Thêm / đổi role
curl -X POST http://<host>/api/spaces/<spaceId>/members \
  -H 'Content-Type: application/json' \
  -d '{"email":"dev1@corp.com","role":"member"}'

# Xoá
curl -X DELETE http://<host>/api/spaces/<spaceId>/members/dev1@corp.com

Người được cấp refresh trang là thấy Space. Không xoá được owner cuối cùng (409) — chống tự khoá mình: cấp owner cho người khác trước rồi mới xoá.

Chi tiết đã kiểm chứng với code: thêm/đổi/xoá thành viên đòi owner (members:admin), xem danh sách (GET /api/spaces/:spaceId/members) chỉ cần viewer trở lên (members:read); email so sánh không phân biệt hoa thường; xoá membership không tồn tại → 404 membership not found; danh sách Space ở GET /api/projects tự lọc theo membership của bạn — chưa được mời thì không thấy, không phải lỗi.

Việc bạn phải nhờ sysadmin​

ViệcVì sao
Deploy, secret, Cloudflare JWT, backup/restore, incident infrangoài phạm vi Space — xem Vận hành
Cấp API key LLM/Embedding, đổi model embedding, re-indexArkon admin — xem Model Catalog
Bypass Human Gate cho 1 task gấpkhông ai làm được — hoặc tắt requireHumanGate ở cấp Space (quyết định của bạn, ghi nhận rủi ro), hoặc chờ admin human approve
Kiểm thử RBAC trên DEV-LITEkhông thể — DEV-LITE bypass mọi request thành owner; dùng DEV FULL-STACK

Checklist tự xác minh​

  • Bootstrap owner hoạt động, log [rbac] applied xuất hiện sau restart.
  • Tạo 1 Space mẫu: provisioning thành công, 5 persona đầy đủ, Wiki Home tồn tại bên Arkon.
  • Mời 1 viewer + 1 member + 1 admin: viewer Approve 403; member tạo/chạy được nhưng approve 403; admin approve được.
  • Xoá owner cuối cùng → 409 đúng kỳ vọng.

Gặp lỗi? Xem Xử lý sự cố.

Đi tiếp: Tạo task & chạy agent · Vận hành hằng ngày

Cập nhật lần cuối vào