> ## Documentation Index > Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Teams > Manage reusable membership for access policies in the dashboard, CLI, or Git Sync A Team is a named set of people, service users, and externally managed [Groups](https://ryvn.ai/docs/guides/groups.md) in your organization. Access policies can use the same Team across multiple grants. Team membership alone grants no permissions: add the Team to an access policy to give its members access. Teams cannot contain other Teams. Group membership remains controlled by your identity provider (IdP), not by the Team. ## Permissions Being a Team member does not give you permission to administer Teams. | Task | Required permissions | | - | - | | List Teams | `team.read` for the organization | | View a Team | `team.read` for that Team | | Create a Team | `team.create` for the organization | | Edit a Team | `team.write` for the Team and `member.manage` for the organization | | Delete a Team | `team.delete` for the Team and `member.manage` for the organization | The member picker also depends on your access to view people, service users, and Groups. Editing access policies requires the relevant policy permissions separately. If an action fails or a control is missing, ask an organization administrator to check your permissions. ## Manage Teams in the dashboard Open **Settings > Teams**. Search by Team name, description, or member details available to you. Click a row to open a view popup with its description and membership. The list's member count counts direct assignments and Group declarations, not the expanded number of people in Groups. ### Create a Team 1. Click **Create Team**. 2. Enter a **Name**: 1–63 lowercase letters, digits, or hyphens, unique among active Teams in the organization. 3. Optionally enter a **Description** of up to 256 characters. 4. In **Members**, select people, service users, or Groups from the searchable picker, then click **Create**. A Team can also be empty. Choose the name carefully: it is immutable. To use another name, create a new Team and update the policies that should use it; editing a YAML name is not a rename operation. ### Edit membership or description Open the row's actions menu and choose **Edit team**. Change **Description** or **Members**, remove unwanted member chips, then click **Save**. **Name** is disabled. Changes affect every access policy that includes the Team. Direct assignments and Group declarations are separate membership sources. Removing a direct assignment does not remove membership obtained through a Group, and removing one Group declaration does not revoke access from other Groups, direct assignments, or policies. Saved members that are inactive or unavailable remain visible and removable rather than being silently discarded. Missing details may reflect permissions or lookup failures; check the person or service user before changing membership. A Group warning may coexist with a saved mapping that still contributes members. See [Group names, mappings, and warnings](https://ryvn.ai/docs/guides/groups.md#names-mappings-and-warnings) before treating a warning as removed access. ### Delete a Team Open the row's actions menu, choose **Delete**, type the Team's name exactly, and click **Delete**. This cannot be undone. Deletion removes its direct assignments and Group declarations, detaches the Team from current access-policy memberships, and removes access supplied through that Team. People, service users, and Groups are not deleted, and their other access sources remain. A policy can remain without members after its Team is removed. Changes that would remove the last organization administrator are blocked. Recreating the same name creates a new Team; it does not restore the live policy memberships removed by deletion. Also review source-controlled policies: a later sync of a `team:` declaration can link to a new Team with that name. ## Grant access through a Team For example, create `staging-readers` with a person, a deployment service user, and the IdP Group `Engineering`. In **Settings > Access Policies**, add `staging-readers` as a Team member of a policy granting the viewer role on the staging environment. The policy supplies the role and resource scope; the Team supplies membership. In policy YAML, the member selector is `team:staging-readers`. Groups cannot be direct policy members. See [access-policy grants](https://ryvn.ai/docs/iac/access-policy#grants) for role and scope syntax and [Groups](https://ryvn.ai/docs/guides/groups.md#how-groups-grant-access) for Group-derived access. ## Use the CLI and YAML [Install and authenticate the CLI](https://ryvn.ai/docs/cli.md), then select the intended organization. Inspect Teams by exact name: ```bash theme={null} ryvn get team ryvn get team staging-readers ryvn describe team staging-readers ryvn get team staging-readers -o json ryvn get team staging-readers -o yaml > team.yaml ``` YAML export requires a named `get team` request. List output and `describe team` do not support YAML. Export includes declared membership, not expanded Group members or Group-resolution diagnostics. A complete Team definition looks like this. The example identities and Group must already exist in the organization; replace them with your own: ```yaml theme={null} kind: Team metadata: name: staging-readers spec: description: Read access to staging members: - user:ops@example.invalid - service-user:deploy-bot - group:Engineering ``` `spec.members` is required and cannot be `null`; use `members: []` for an empty Team. Selectors use a person's email, a service user's name, or an exact Group display name, preserving case and spaces. There is no `team:` selector inside a Team and no inline permission grant. Use these commands for the corresponding operation, not as a sequence to run: | Operation | Command | | - | - | | Create from a complete definition | `ryvn create -f team.yaml` | | Patch only the description | `ryvn update team staging-readers -p '{"spec":{"description":"Staging viewers"}}'` | | Replace from a complete definition | `ryvn replace -f team.yaml` | | Delete by exact name | `ryvn delete team staging-readers` | A supplied `members` list replaces both direct assignments and Group declarations; include everything you intend to keep. Omitting `members` from an update patch preserves membership, but omission is not valid in a complete create/replace definition. CLI deletion does not use the dashboard's typed-name confirmation. ## Git Sync, plans, and drift Store Team definitions in your [Git Sync resource files](https://ryvn.ai/docs/configure/infrastructure-as-code.md#resource-file-structure). Preview a candidate without applying it: ```bash theme={null} ryvn plan -f team.yaml ryvn plan -f team.yaml -o json ``` Plans can report declared membership changes, Group-mapping effects, and drift blockers. Review notices as well as changes; use `ryvn plan --help` for planning options. An IdP Group membership change changes who is included through that Group, not the Team's declared YAML member list. In **Infra as Code > Resources**, inspect Team sync status, source file, commit, and last sync. The source-file link opens GitHub; the Team resource link opens **Settings > Teams**. Teams use forms and view popups, not an in-page YAML editor or drift banner. Dashboard or API edits to a git-managed Team can trigger drift protection. For the generic behavior, see [how drift protection works](https://ryvn.ai/docs/guides/drift-protection.md#how-it-works); its resource-page banner instructions do not apply to Teams. Use the [CLI drift-resolution workflow](https://ryvn.ai/docs/guides/drift-protection.md#resolving-drift-from-the-cli) and [Git Sync selectors](https://ryvn.ai/docs/cli.md#git-sync-selectors) when you intend git to overwrite protected changes.