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

# Roles

> Define permissions and control what users can do

Roles are collections of permissions that define what actions users can perform. Assign roles to users directly or through groups.

## System vs Custom Roles

* **System Roles**: Pre-defined by ShiftLabs. Cannot be modified or deleted.
* **Custom Roles**: Created by your organization. Fully customizable.

## How to Create a Custom Role

<Steps>
  <Step title="Open Create Panel">
    Go to **Access Management → Roles** and click **Create Role**.
  </Step>

  <Step title="Enter Role Details">
    * **Role Key** (required): Unique identifier (lowercase, dashes allowed). Cannot be changed later.
    * **Display Name** (required): Friendly name shown in the UI.
    * **Description** (optional): Explain the role's purpose.
  </Step>

  <Step title="Select Permissions">
    Click the **Permissions** tab. The tree shows:

    * **Services** (e.g., KodeInfra, IAM, CI/CD)
      * **Resources** (e.g., Cluster, Pipeline)
        * **Permissions** (e.g., Read, Write, Delete)

    Check a service to select all its permissions, or expand to pick individual ones.
  </Step>

  <Step title="Save">
    Click **Create Role**. The role is now available to assign.
  </Step>
</Steps>

## How to Edit a Role

<Steps>
  <Step title="Open Role">
    Go to **Access Management → Roles** and click on the role.
  </Step>

  <Step title="Modify Details or Permissions">
    * **Details tab**: Update display name or description
    * **Permissions tab**: Check/uncheck permissions
  </Step>

  <Step title="Save">
    Click **Save Details** or **Save Permissions**.
  </Step>
</Steps>

<Warning>
  System roles cannot be edited. Create a custom role with similar permissions instead.
</Warning>

## How to Delete a Role

<Steps>
  <Step title="Open Role">
    Go to **Access Management → Roles** and click on the custom role.
  </Step>

  <Step title="Delete">
    Scroll to **Danger Zone** and click **Delete**.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. All users and groups with this role will lose its permissions.
  </Step>
</Steps>

<Warning>
  System roles cannot be deleted.
</Warning>

## How to Assign Roles

**To a user:**

1. Go to **Access Management → Users** → click user → **Roles** tab
2. Check the roles to assign
3. Click **Save Changes**

**To a group:**

1. Go to **Access Management → Groups** → click group → **Roles** tab
2. Check the roles to assign
3. Click **Save Changes**

All group members inherit the roles immediately.

<Tip>
  Prefer assigning roles to groups rather than individual users for easier management.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot edit or delete a role">
    It's likely a **System Role** (indicated by lock icon). System roles cannot be modified. Create a custom role instead.
  </Accordion>

  <Accordion title="User doesn't have expected access">
    1. Check if the correct role is assigned (directly or via group)
    2. Verify the role includes the required permissions
    3. Remember: permissions combine from all roles
  </Accordion>

  <Accordion title="Role key already exists">
    Keys must be unique. Try: `developer-2`, `k8s-admin-team-a`, `custom-viewer`
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can a user have multiple roles?">
    Yes. Permissions from all roles are combined.
  </Accordion>

  <Accordion title="What happens when I delete a role?">
    All users and groups lose that role's permissions immediately.
  </Accordion>

  <Accordion title="Can I change a role key after creation?">
    No. The key is permanent. You can change the display name anytime.
  </Accordion>

  <Accordion title="Are role changes immediate?">
    Yes. Permission changes take effect immediately for all affected users.
  </Accordion>

  <Accordion title="What if two roles have overlapping permissions?">
    Permissions are combined (union). No conflict—users get all permissions from all their roles.
  </Accordion>
</AccordionGroup>