> ## 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.

# Projects

> Organize resources and control access with project-based isolation

Projects group related resources (clusters, pipelines, storage) and control who can access them. Use projects to separate environments, teams, or applications.

## How to Create a Project

<Steps>
  <Step title="Open Projects Page">
    Go to **Access Management → Projects** and click **Create Project**.
  </Step>

  <Step title="Enter Project Details">
    * **Project Key**: Unique identifier (lowercase, dashes allowed). Cannot be changed later.
    * **Display Name**: Friendly name shown in the UI.
    * **Description**: Optional explanation of the project's purpose.
  </Step>

  <Step title="Save">
    Click **Create Project**. You can now add members and groups.
  </Step>
</Steps>

## How to Add Members to a Project

Members get direct access to project resources based on their assigned roles.

<Steps>
  <Step title="Open Project">
    Go to **Access Management → Projects** and click on the project.
  </Step>

  <Step title="Go to Members Tab">
    Click the **Members** tab, then click **Add Member**.
  </Step>

  <Step title="Select User and Roles">
    Choose a user from the list, then select one or more roles for them.
  </Step>

  <Step title="Confirm">
    Click **Add Member**. The user now has access to this project.
  </Step>
</Steps>

<Tip>
  To modify a member's roles later, click the shield icon on their card.
</Tip>

## How to Add Groups to a Project

Adding a group gives all its members access to the project.

<Steps>
  <Step title="Open Project">
    Go to **Access Management → Projects** and click on the project.
  </Step>

  <Step title="Go to Groups Tab">
    Click the **Groups** tab, then click **Add Group**.
  </Step>

  <Step title="Select Group and Roles">
    Choose a tenant group, then select which roles the group should have in this project.
  </Step>

  <Step title="Confirm">
    Click **Add Group**. All group members now have project access.
  </Step>
</Steps>

<Info>
  Groups are more efficient than individual assignments. Add users to a tenant group, then assign the group to projects.
</Info>

## How to Remove Members or Groups

* **Remove Member**: Click the remove icon on the member's card in the Members tab.
* **Remove Group**: Click the remove icon on the group's card in the Groups tab.

<Warning>
  Removing a group immediately revokes access for all its members (unless they also have direct membership).
</Warning>

## Permission Inheritance

Users receive project permissions from two sources:

1. **Direct Membership** - Roles assigned in the project's Members tab
2. **Group Membership** - Roles inherited from groups assigned to the project

Permissions from all sources are combined.

## Default Project

Every organization has one **Default** project (marked with a star). New users without explicit assignment may be added here automatically.

* The default project cannot be deleted
* Only one project can be default at a time

## Troubleshooting

<AccordionGroup>
  <Accordion title="User cannot access project resources">
    1. Check if the user is a project member (directly or via group)
    2. Verify the assigned roles have the required permissions
    3. Confirm the project is active
  </Accordion>

  <Accordion title="Cannot delete a project">
    * The default project cannot be deleted (change default first)
    * Projects with resources may need resources deleted first
  </Accordion>

  <Accordion title="Project key already exists">
    Keys must be unique. Try: `prod-team-a`, `staging-2`, `dev-frontend`
  </Accordion>

  <Accordion title="Group members don't have expected access">
    1. Verify the group is assigned to the project
    2. Check the group's roles in the project have correct permissions
    3. Confirm the user is actually in the group
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can a user be in multiple projects?">
    Yes, with different roles in each. Permissions are scoped per project.
  </Accordion>

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

  <Accordion title="What happens when I delete a project?">
    The project, all its resources, and all member/group assignments are permanently deleted.
  </Accordion>

  <Accordion title="What's the difference between project roles and tenant roles?">
    Tenant roles apply organization-wide. Project roles apply only within that specific project.
  </Accordion>
</AccordionGroup>