> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom roles and permissions

> Create and manage custom roles with granular permissions for your Enterprise organization in CodeRabbit.

export const AdminRoleBadge = ({tip = "This feature requires an organization owner, an admin role or the corresponding permission. Regular Members do not have access.", title = "Admin Only", cta = "View roles", href = "/management/roles", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="lock" color="orange" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const EnterprisePlanBadge = ({tip = "This feature is available exclusively as part of the Enterprise plan. Please refer to our pricing page for more information about our plans and features.", title = "Enterprise Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="building-2" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<EnterprisePlanBadge />

<AdminRoleBadge tip="Members do not have access to Roles and permissions. Admin and Billing Admin users can view the page. Only Admin users can create, edit, delete, or set default custom roles." />

## Overview

CodeRabbit includes three built-in system roles — **Admin**, **Member**, and **Billing Admin** — that cover common access patterns. With Custom RBAC (Role-Based Access Control), Enterprise customers can go further by defining additional roles with specific permissions tailored to their organization's structure and workflows. Each custom role controls access to individual resources at one of three levels: no access, read only, or read and write. Once created, custom roles are available across your organization, including in Team Management for per-user assignment.

<CardGroup cols={2}>
  <Card title="Custom role creation" icon="circle-plus">
    Create roles with a unique name and an optional description to reflect their purpose in your organization.
  </Card>

  <Card title="Granular permissions" icon="user-lock">
    Control access to each resource independently using **No access**, **Read only**, or **Read and Write** — giving you precise control over what each role can do.
  </Card>

  <Card title="Default role assignment" icon="star">
    Designate any custom role as the default so new users joining your organization are automatically assigned the right level of access.
  </Card>

  <Card title="Team Management integration" icon="users">
    Assign custom roles to individual users directly from the Team Management page, alongside the built-in system roles.
  </Card>
</CardGroup>

<Info>
  **Navigation paths for Roles and permissions settings:**

  * **Cloud:** `/settings/roles-permissions`
  * **Self-hosted:** `/settings/account/roles-permissions`
</Info>

***

## View roles and permissions

<Steps>
  <Step title="Navigate to Roles and permissions">
    Go to your organization settings and open the **Roles and permissions** page. You will see a table listing all roles in your organization.
  </Step>

  <Step title="Review the roles table">
    The table displays the following columns for each role:

    * **Role name** — the display name of the role
    * **Role type** — labeled **System** for built-in roles (Admin, Member, Billing Admin) or **Custom** for user-created roles
    * **Description** — optional text describing the role's purpose
    * **Number of assigned users** — how many users currently hold this role
    * **Default role indicator** — a star (★) icon marks the role that is automatically assigned to new users
  </Step>

  <Step title="Search for a role">
    Use the **Search** field at the top of the table to filter roles by name or description. Results update as you type, making it easy to find a specific role in large organizations.
  </Step>

  <Step title="Filter by role type">
    Use the **Filter** dropdown to narrow the list by type:

    * **All** (default) — shows every role
    * **System** — shows only the built-in Admin, Member, and Billing Admin roles
    * **Custom** — shows only user-created custom roles
  </Step>
</Steps>

***

## Create a custom role

<Steps>
  <Step title="Navigate to Roles and permissions">
    Go to your organization settings and open the **Roles and permissions** page.
  </Step>

  <Step title="Open the creation form">
    Click the **Create role** button in the top-right corner of the page. A creation form will appear.
  </Step>

  <Step title="Enter a name">
    Enter a **Name** for the role. This field is required. Role names must be unique within your organization — if the name is already taken, a validation message will appear and the form cannot be submitted until you choose a different name.
  </Step>

  <Step title="Add an optional description">
    Optionally enter a **Description** to explain what the role is for and who should be assigned to it. A good description helps administrators understand the role's purpose at a glance.
  </Step>

  <Step title="Save the role">
    Click **Save**. The new role is created and automatically populated with the default member role permissions as a baseline.
  </Step>

  <Step title="Configure permissions">
    After saving, you are taken to the role detail page where you can adjust the permission matrix to match the access level intended for this role. See [Edit role permissions](#edit-role-permissions) below.
  </Step>
</Steps>

***

## Duplicate an existing role

Duplicating a role copies all of its permission settings into a new role, saving time when you need a role that is similar to an existing one.

<Steps>
  <Step title="Locate the role to duplicate">
    On the **Roles and permissions** page, find the role you want to duplicate in the table.
  </Step>

  <Step title="Open the Actions menu">
    Click the **Actions** menu (the three-dot ⋯ icon) at the far right of the role's row.
  </Step>

  <Step title="Select Duplicate">
    Select **Duplicate** from the dropdown menu. A new role is immediately created with all the same permissions as the original. The new role's name is prefixed with **"Copy of"** followed by the original role name.
  </Step>

  <Step title="Rename and adjust">
    Click the duplicated role's name to open its detail page. Update the name, description, and any permissions as needed.
  </Step>
</Steps>

***

## Edit role permissions

### Role detail page

When you open a custom role by clicking its name on the Roles and permissions page, the detail page displays the following metadata:

* **Assigned users** — the number of users currently assigned to this role
* **Role type** — **System** or **Custom**
* **Created by** — the user who created the role
* **Created on** — the date the role was created

### Permission matrix

Each resource can be configured independently. Select the access level that applies to this role for each resource:

| Resource              | No access | Read only | Read and Write |
| --------------------- | --------- | --------- | -------------- |
| Organization settings | ✓         | ✓         | ✓              |
| Repository settings   | ✓         | ✓         | ✓              |
| Reports               | ✓         | ✓         | ✓              |
| Learnings             | ✓         | ✓         | ✓              |
| Team Management       | ✓         | ✓         | ✓              |
| Billing               | ✓         | ✓         | —              |
| API access            | ✓         | ✓         | —              |

<Warning>
  System roles — **Admin**, **Member**, and **Billing Admin** — are view-only and cannot be edited. Their permission matrices are displayed for reference but all controls are disabled.
</Warning>

### Save or discard changes

<Steps>
  <Step title="Navigate to the role detail page">
    On the **Roles and permissions** page, click the name of the custom role you want to edit. The role detail page opens, showing the permission matrix.
  </Step>

  <Step title="Set access levels">
    For each resource in the permission matrix, select the desired access level using the radio buttons:

    * **No access** — the role cannot see or interact with this resource
    * **Read only** — the role can view this resource but cannot make changes
    * **Read and Write** — the role can view and modify this resource
  </Step>

  <Step title="Apply or cancel">
    Click **Save** to apply your changes. Click **Discard** to cancel all unsaved changes and revert to the previously saved state.
  </Step>
</Steps>

***

## Set a default role

The default role is automatically assigned to new users when they join your organization, ensuring they have the appropriate baseline access without requiring manual role assignment.

<Steps>
  <Step title="Navigate to Roles and permissions">
    Go to your organization settings and open the **Roles and permissions** page.
  </Step>

  <Step title="Open the Actions menu">
    Click the **Actions** menu (the three-dot ⋯ icon) next to the role you want to set as the default.
  </Step>

  <Step title="Set as default">
    Select **Set as default** from the dropdown menu. The role now displays a star (★) icon in the **Default** column of the table, confirming it is the active default role.
  </Step>

  <Step title="Remove default status">
    To remove the default designation without assigning a new default, click the **Actions** menu next to the current default role and select **Remove as default**.
  </Step>
</Steps>

<Info>
  Only one role can be the default at a time. Setting a new role as default automatically removes the default designation from the previously assigned role.
</Info>

***

## Delete a custom role

<Info>
  Deletion is blocked when one or more users are assigned to the role. All users must be reassigned to a different role before deletion is possible. Additionally, if the role being deleted is currently set as the default role, its default status is automatically removed before deletion proceeds.
</Info>

<Tip>
  Reassign all users to another role before attempting to delete a custom role. Check the **Assigned users** count in the table — if it is greater than 0, navigate to **Team Management** to reassign those users first.
</Tip>

<Steps>
  <Step title="Navigate to Roles and permissions">
    Go to your organization settings and open the **Roles and permissions** page.
  </Step>

  <Step title="Verify no users are assigned">
    Check the **Assigned users** count in the row for the role you want to delete. If the count is greater than 0, go to **Team Management** and reassign those users to a different role before continuing.
  </Step>

  <Step title="Open the Actions menu">
    Click the **Actions** menu (the three-dot ⋯ icon) next to the role.
  </Step>

  <Step title="Select Delete">
    Select **Delete** from the dropdown menu.
  </Step>

  <Step title="Confirm deletion">
    A confirmation dialog will appear asking you to confirm the deletion. Confirm to permanently remove the role. This action cannot be undone.
  </Step>
</Steps>

***

## Assign roles in Team Management

The **Team Management** page supports both system and custom roles in the role selector, allowing you to assign any role — built-in or custom — to individual users.

<Info>
  Only organization members can be assigned custom roles. Non-org users may still appear in **Team Management**, but custom roles are not available for them.
</Info>

<Steps>
  <Step title="Navigate to Team Management">
    Go to your organization settings and open the **Team Management** page.
  </Step>

  <Step title="Locate the user">
    Find the user whose role you want to change in the members list. Use the search field or scroll through the list to locate them.
  </Step>

  <Step title="Open the Role dropdown">
    Click the **Role** dropdown next to the user's name. The dropdown displays all available roles — both system roles (Admin, Member, Billing Admin) and any custom roles you have created.
  </Step>

  <Step title="Select the new role">
    Select the desired role from the dropdown. The change is applied immediately using an optimistic update, so the UI reflects the new role right away.
  </Step>

  <Step title="Handle errors">
    If the update fails (for example, due to a permissions issue or network error), the role assignment is automatically rolled back to the previous value and an error message is displayed. Retry the change or contact your administrator if the problem persists.
  </Step>
</Steps>

**Filter members by role:** Use the **Role** filter dropdown in the members list header to display only users assigned to a specific role. This filter includes custom roles, making it easy to audit who has been assigned each custom role in your organization.

***

## What's next

<CardGroup cols={1}>
  <Card title="Roles overview" icon="users" href="/management/roles" horizontal>
    Learn about the built-in Admin, Member, and Billing Admin roles and how they differ from custom roles.
  </Card>

  <Card title="Seat assignment" icon="user-check" href="/management/seat-assignment" horizontal>
    Manage user seats and access in your organization.
  </Card>
</CardGroup>