Teams are groups of organization members that reflect your company or group's structure with cascading access permissions and mentions.

List of teams in an organization

Organization owners and team maintainers can give teams admin, read, or write access to organization repositories. Organization members and outside collaborators can send a notification to an entire team by mentioning the team's name.

Image of a team mention

Team visibility

Teams can be visible or secret:

  • Visible teams can be viewed and @mentioned by every organization member.
  • Secret teams are only visible to the people on the team and people with owner permissions. They're great for hiding teams with sensitive names or members, such as those used for working with external partners or clients. Secret teams cannot be nested under parent teams or have child teams.

Nested teams

You can reflect your group or company's hierarchy within your GitHub organization with multiple levels of nested teams. A parent team can have multiple child teams, while each child team only has one parent team. You cannot nest secret teams.

Child teams inherit the parent's access permissions, simplifying permissions management for large groups. Members of child teams also receive notifications when the parent team is @mentioned, simplifying communication with multiple groups of people.

For example, if your team structure is Employees > Engineering > Application Engineering > Identity, granting Engineering write access to a repository means Application Engineering and Identity also get that access. If you @mention the Identity Team or any team at the bottom of the organization hierarchy, they're they only ones who will receive a notification.

Teams page with a parent team and child teams

To easily understand who shares a parent team's permissions and mentions, you can see all of the members of a parent team's child teams on the parent team's page. Members of a child team are not direct members of the parent team.

Parent team page with all members of child teams

Preparing to nest teams in your organization

If your organization already has existing teams, you should audit each team's repository access permissions before you nest teams above or below it. You should also consider the new structure you'd like to implement for your organization.

At the top of the team hierarchy, you should give parent teams repository access permissions that are safe for every member of the parent team and its child teams. As you move toward the bottom of the hierarchy, you can grant child teams additional, more granular access to more sensitive repositories.

  1. Remove all members from existing teams
  2. Audit and adjust each team's repository access permissions and give each team a parent
  3. Create any new teams you'd like to, choose a parent for each new team, and give them repository access
  4. Add people directly to teams

Further reading