How to Set Up Role-Based Access Control for a Multi-Team Project

When several teams share one delivery workspace, “everyone can do everything” stops being convenient and starts being a liability. Role-based access control lets you give each person exactly the access their job needs — and nothing more. KazTrack ships granular, per-project RBAC with four built-in roles plus custom roles you define yourself, so a contractor can record QA results without touching deploys, and a delivery lead can manage sprints without owning billing. This tutorial walks through configuring RBAC for a multi-team project.

Prerequisites

• A KazTrack project where you are the owner or a manager with roles.manage.
• A list of the people and teams who need access.
• A rough idea of what each group should and shouldn’t be able to do.

Step 1: Understand the built-in roles

Every project starts with four system roles. Their slugs match their labels:

• owner — full control, including managing roles and billing. Assigned to the creator at provisioning; it cannot be removed or demoted, and it never appears in the assign-role dropdown.
• manager — everything except managing roles (roles.manage). Runs sprints, repos, labels, settings, and reports.
• tester — logs working time, records test results, and works PRs.
• viewer — read-only visibility.

These cover most teams out of the box. Reach for custom roles only when a real responsibility doesn’t fit one of these.

Step 2: Map teams to responsibilities

Before assigning anything, sketch who does what. A simple matrix keeps you honest:

Group                Needs to...                          Likely role
Core engineers       open PRs, run sprints, deploy        manager
QA contractors       record test results, log time        tester
Stakeholders         view progress only                   viewer
Release captains     manage sprints, not roles/billing    custom

Designing around responsibilities — not job titles — produces a cleaner permission set and fewer one-off exceptions later.

Step 3: Invite members and assign a starting role

1. Open Members in your project.
2. Invite each person by email.
3. Assign a built-in role as their starting point.

Assignment rules to remember:

• The owner is fixed and not offered in the dropdown.
• The owner cannot be removed or demoted, which protects the project from being orphaned.
• Granting a role that itself carries roles.manage requires you to hold roles.manage — an escalation guard so members can’t quietly promote themselves to role administrators.

Step 4: Create a custom role when built-ins don’t fit

When a responsibility falls between roles, define a custom per-project role at Roles (/projects/{slug}/roles). KazTrack exposes a permission catalog — capabilities like sprints.manage, issues.verify, repositories.manage, reports.view_all, settings.github, and roles.manage — and a custom role is simply a named bundle of these.

Example: a Release Captain who runs delivery but shouldn’t administer roles or billing.

Role: Release Captain (slug: release-captain)
Permissions:
  - sprints.manage
  - repositories.manage
  - labels.manage
  - reports.view_all
Excludes:
  - roles.manage
  - billing.manage

Save it, and it becomes assignable just like the built-in roles. Custom roles are scoped to this project only, so another project’s setup is unaffected.

Step 5: Verify the permission gates

RBAC means nothing if it isn’t enforced consistently. KazTrack gates access in three places, all reading from the same permission set:

• Routes — pages check a permission before rendering (for example, the sprints area requires sprints.manage).
• Policies and actions — server-side checks confirm the permission again on every mutation, so a hand-crafted request can’t bypass the UI.
• MCP tools — an agent’s token can never exceed its owner’s permissions; mutating tools enforce the same gate as the matching web action.

To verify, sign in as (or impersonate, if you have admin access) a tester and confirm the sprint-management and role-management areas are hidden or refused. The frontend reads the active project’s permissions, so the UI itself adapts per role — a viewer simply won’t see edit controls.

Step 6: Apply RBAC to deploys, reports, and QA

Walk through the surfaces that matter most for a multi-team project:

• Deploys — deployment via Laravel Forge and xCloud is permission-gated. Keep deploy rights with engineers and release captains; testers and viewers don’t get them.
• Reports — reports.view_all shows the whole team’s working-time data; members with only sessions.log see just their own. This is how a contractor tracks their hours without seeing everyone else’s.
• QA — testers record results and verify issues; viewers can read the outcomes but not change them.

Assigning the narrowest role that still lets someone do their job is the core RBAC discipline.

Step 7: Review access on a schedule

Access tends to accumulate. Set a recurring review — monthly or per release:

1. Open Members and scan every role assignment.
2. Downgrade anyone whose project ended (contractor finished, stakeholder no longer involved).
3. Audit custom roles for permissions that crept in but are no longer needed.
4. Confirm the owner is still the right person; transfer ownership deliberately if not.

Because roles are per-project, a person can be a manager in one project and a viewer in another — review each project on its own terms.

Troubleshooting

• Can’t assign a role — you need roles.manage yourself, and you cannot grant a role carrying roles.manage unless you hold it (escalation guard).
• A member sees too much — they’re on a broader role than intended. Move them to a narrower built-in or custom role; the UI updates from the active project’s permissions on their next load.
• An MCP agent did something a role shouldn’t allow — the token’s owner actually had that permission. Tokens mirror UI permissions exactly, so adjust the owner’s role, not the token.
• You can’t demote the owner — by design. Transfer ownership first if the project needs a new owner.

Key takeaways

Setting up role-based access control for a multi-team project comes down to mapping responsibilities, starting with the four built-in roles, and defining custom roles only where a real gap exists. The same permission set gates routes, server actions, and MCP agents, so access stays consistent no matter how someone connects. Configure roles in KazTrack before your next team joins, and give everyone exactly the access their work requires.