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

# Organization Teams

> Group GitHub repositories into reusable organization teams for access control and team-level configuration.

CodeAnt **Organization Teams** group related repositories into a reusable hierarchy. Use them to grant access to several repositories at once and, on supported settings pages, apply one configuration to a group of repositories.

<Note>
  **Organization Teams**, **DORA Metrics Teams**, **Team Management**, and the **Microsoft Teams integration** are different features:

  * **Organization Teams** group repositories for access control and team-level configuration.
  * **DORA Metrics Teams** group repositories for aggregated engineering metrics. Manage them separately in [DORA Metrics](/engineering_productivity/dora_metrics#team-control).
  * **Team Management** manages people, administrator/member status, and product seats.
  * **Microsoft Teams** sends CodeAnt notifications to Microsoft Teams channels.
</Note>

## Availability and permissions

The **Settings → Teams** page is currently available for GitHub organizations, including GitHub Enterprise organizations connected as the GitHub provider. An organization administrator is required to create, edit, sync, or delete teams.

For GitLab, Bitbucket, and Azure DevOps, use repository-scoped assignments in [Access Control](/settings/access-control). Team-scoped assignments are currently available through the CodeAnt UI only for GitHub organizations.

## Create an organization team

1. In [CodeAnt AI](https://app.codeant.ai), switch to the GitHub organization you want to configure.
2. Open **Settings → Teams**.
3. Click **New Team**.
4. Enter a name and, optionally, a description.
5. Set the team to **Active** or **Inactive**. Inactive teams are excluded from the active hierarchy and from new team-scoped access choices.
6. Optionally add existing teams under this team. A parent team can be used to group several child teams.
7. Choose the repositories covered by the team:
   * Select **Include all repositories** to cover every current and future repository in the organization.
   * Otherwise, add individual repositories.
8. Click **Create Team**.

<Tip>
  Use **Include all repositories** for organization-wide groups such as Platform or Security. Use an explicit repository list for product or service teams whose boundary should not expand automatically.
</Tip>

## Organization team hierarchy

Organization teams support flexible repository structures:

* A team can contain repositories and child teams.
* A child team can belong to more than one parent team.
* A repository can belong to more than one team.
* An access assignment on a parent team covers repositories in its descendant teams.
* An **all repositories** team also covers repositories added in the future.

For example:

```text theme={"system"}
Engineering
├── Platform
│   ├── acme/api
│   └── acme/infrastructure
└── Product
    ├── acme/web
    └── acme/mobile
```

Assigning a role to **Engineering** covers all four repositories. Assigning it to **Platform** covers only `acme/api` and `acme/infrastructure`.

<Warning>
  A repository can belong to multiple teams, so keep overlapping teams intentional. Access permissions from every matching assignment are combined. Team-level configuration follows one deterministic inheritance path; avoid defining conflicting configuration in overlapping teams.
</Warning>

## Sync organization teams from GitHub

To import your existing GitHub team structure, open **Settings → Teams** and click **Sync from GitHub**.

The sync:

* creates missing CodeAnt teams;
* updates existing teams that have the same slug;
* imports team names, descriptions, parent/child relationships, and repositories; and
* preserves the GitHub hierarchy.

The sync does **not** import GitHub team members or GitHub repository permission levels. Manage CodeAnt users in **Settings → Team Management**, then grant CodeAnt permissions in [Access Control](/settings/access-control).

## Apply configuration at team scope

Settings pages that support team-level configuration show **Teams** in the scope selector. Select a team to save the setting once for all repositories that resolve through that team.

For a repository, CodeAnt resolves supported configuration from most specific to least specific:

1. Repository
2. Direct team
3. Parent team, continuing up the hierarchy
4. Organization

A more specific value overrides a broader value. If a repository is in multiple teams, CodeAnt uses a deterministic path beginning with the earliest-created matching team, then the earliest-created parent at each level.

<Note>
  Not every settings page supports team scope. If the scope selector on a page does not list **Teams**, configure that feature at one of the levels offered on that page.
</Note>

## Edit or delete a team

Use the actions beside a team to change its name, description, status, child teams, or repositories.

Before deleting a team:

* remove it from any parent teams that currently group it;
* review [Access Control](/settings/access-control) assignments that reference it; and
* decide whether those users need replacement repository or team assignments.

Deleting a team does not delete its repositories or child teams. They remain in CodeAnt but are no longer grouped under the deleted team.

## Common team designs

| Design             | Structure                                                                         | Why use it                                                                                     |
| ------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Product teams      | One team per product or service                                                   | Grant product engineers access to only their repositories.                                     |
| Platform hierarchy | A Platform parent with Infrastructure, Developer Experience, and Runtime children | Grant platform-wide access at the parent or narrower access at a child.                        |
| Security coverage  | An all-repositories Security team                                                 | Cover current and future repositories without maintaining a list.                              |
| Shared repository  | Put one repository in multiple teams                                              | Let separate groups inherit access to a shared service. Review combined permissions carefully. |

Next, see [Access Control](/settings/access-control) to create roles and assign them to users at a team or repository scope.