GitHub Organizations and Teams

Run shared projects in a GitHub organization: members and roles, teams with repository access, outside collaborators, rulesets across repositories, and good habits for joining and leaving.

Lesson 17 of 30Advanced17 min read

A personal GitHub account is perfect for your own projects. But when a company, a school club or an open-source community works on code together, keeping everything under one person's account causes problems. What happens when that person leaves? How do you give the design team access to the website but not to the payment service? How do ten people manage forty repositories without inviting everyone to each one individually?

Organizations solve this. An organization is a shared account that owns repositories, with its own members, teams and settings. Access is granted to teams rather than to individuals one repository at a time, and rules such as "every repository's main branch needs a review" can be applied across the whole organization at once.

In this lesson you'll set up an organization, teams and access levels, apply rules across repositories, and handle people joining and leaving.

Organizations and roles

Create one from the + menu, then New organization. Every plan covers public and private repositories with the core features; paid plans add advanced security and administration tools.

RoleCan
OwnerEverything: billing, settings, members, deleting the organization
MemberJoin teams, see members, create repositories (if allowed)
Outside collaboratorAccess only the specific repositories they're added to

Have at least two owners, so the organization is never locked if one person is unavailable. Members join by invitation, using their own personal GitHub accounts: one person can belong to several organizations with a single account.

Teams and repository access

A team is a group of members, such as frontend, backend or docs. Give each team a role on each repository it needs:

RoleAllows
ReadView and clone, open issues and comment
TriageManage issues and pull requests
WritePush branches and merge pull requests
MaintainManage the repository without sensitive settings
AdminFull control, including settings and deletion

When someone joins the frontend team, they instantly get exactly the frontend team's access everywhere, and when they leave the team, it's removed everywhere. Teams can be nested: a web parent team containing frontend and backend passes its access down to both.

Mentions, code owners and discussions

Teams are also a way to reach the right people:

  • Mention @acme/frontend in an issue or pull request to notify the whole team.
  • Request a review from a team, and GitHub can assign a member automatically, spreading reviews fairly.
  • In a CODEOWNERS file, list teams rather than individuals: /web/ @acme/frontend. When people change jobs, you update the team, not every file.

Base permissions in the organization's settings decide what every member can do by default, such as read all repositories. Start with the lowest that works, and grant more through teams.

Rulesets, security and leaving

Organization rulesets apply branch protection to many repositories at once, for example: on every repository's main, require a pull request, one approval and passing status checks. One rule set in one place is far easier to keep consistent than separate settings in forty repositories.

Under Authentication security, owners can require two-factor authentication for all members. The organization's audit log records who changed settings, permissions and repositories.

When someone leaves, remove them from the organization; their team access disappears with them. Any personal access tokens, SSH keys or deploy keys they set up for automation should be replaced with organization-owned credentials. Repositories can be moved into an organization with Settings, Transfer ownership, and GitHub redirects the old address.

GitHub Organizations Syntax

Organization essentials

+ > New organization                         create an organization
People > Invite member                       add someone by username or email
Teams > New team                             create a team (can be nested)
Repository > Settings > Collaborators and teams > Add teams
@acme/frontend                               mention or request review from a team
/web/  @acme/frontend                        CODEOWNERS entry for a team
Settings > Rules > Rulesets                  rules across repositories
Settings > Authentication security           require two-factor authentication
Repository > Settings > Transfer ownership   move a repository into the organization
gh api orgs/acme/teams --jq '.[].name'
gh repo create acme/website --private

GitHub Organizations Summary

  • Organizations own shared repositories, with owners, members and outside collaborators.
  • Teams group members; give teams Read, Triage, Write, Maintain or Admin access to repositories.
  • Mention and request reviews from teams, and use teams in CODEOWNERS.
  • Rulesets apply branch protection across many repositories; owners can require 2FA for everyone.
  • Keep at least two owners, use low base permissions and remove leavers from the organization.

GitHub Organizations Examples

Each example shows the code, the output it produces and what each part does.

Example 1

Setting up a small company organization

Text
Organization: acme
Owners: priya, tom                         (two owners)
Base permission: Read

Teams:
  web (parent)
    frontend   -> website: Write, design-system: Write
    backend    -> api: Write, website: Read
  docs         -> website: Triage, docs: Write
Outside collaborators:
  freelancer-li -> design-system: Write   (contract ends in June)
Output
A new frontend developer is invited and added to "frontend".
They can immediately push to website and design-system,
read every other repository, and change nothing else.
Line-by-line explanation
  1. Line 2Two owners, so the organization never depends on one person.
  2. Line 3Every member can read every repository; anything more comes from teams.
  3. Lines 6 to 9Access is planned by team and repository, not by individual.
  4. Lines 10 to 11A contractor gets access to exactly one repository, without joining the organization.
Example 2

Team reviews with CODEOWNERS

Text
# .github/CODEOWNERS in acme/website
*            @acme/frontend
/api-client/ @acme/backend
/docs/       @acme/docs
*.css        @acme/frontend @priya
Output
A pull request changing docs/setup.md requests a review from @acme/docs.
A pull request changing api-client/user.js requests @acme/backend.
With "Require review from Code Owners" in a ruleset, the PR can't
merge until someone from the right team approves.
Line-by-line explanation
  1. Line 2The default: frontend owns everything not matched below.
  2. Lines 3 to 4Later lines take priority for their paths.
  3. Line 5Teams and individuals can be combined.
Example 3

One ruleset for every repository

Text
Ruleset: "Protect main"
  Target: all repositories, branch: default branch
  Rules:
    Require a pull request before merging
      Required approvals: 1
      Require review from Code Owners
    Require status checks to pass: ci / test
    Block force pushes
  Bypass list: Organization admins (emergencies only)
Output
The rule applies to all 40 repositories at once. A new repository
created tomorrow is protected automatically.
Line-by-line explanation
  1. Line 2Applied to the default branch of every repository in the organization.
  2. Lines 4 to 7The same protections as branch protection rules, defined once.
  3. Line 8Force pushes to main are blocked everywhere.
  4. Line 9Bypasses are kept to a short, named list.

Common GitHub Organizations Mistakes

A single owner

Don't
Owners: tom                      # Tom leaves: nobody can change settings or billing
Do
Owners: tom, priya               # at least two, with 2FA turned on

Giving everyone admin

Don't
Base permission: Admin           # anyone can delete any repository
Do
Base permission: Read            # grant Write or Admin through teams where needed

Forgetting automation when someone leaves

Don't
Remove the person, but deployments still use their personal access token
Do
Replace personal tokens and keys with organization-owned ones before removing them

GitHub Organizations in Real Projects

Organizations in practice

Almost every company and open-source project on GitHub uses an organization, from huge ones like Microsoft's to small startups and student clubs, because projects outlive any one member.

GitHub Organizations FAQ

Is it free to create a GitHub organization?

Yes. The free plan for organizations includes unlimited public and private repositories and unlimited members. Paid plans add features such as more advanced security and access controls, which larger teams may need.

How do I move my repository into an organization?

Use the transfer option in the repository's Settings and choose the organization; you need permission to create repositories there. Issues, pull requests, stars and history move with it, and GitHub redirects the old URL. Update local clones with git remote set-url anyway.

Can a team contain other teams?

Yes. Teams can be nested, with a child team inheriting the repository access of its parent. For example, an Engineering team can contain Frontend and Backend teams, so a mention of the parent team notifies everyone in both.

Can I be a member of more than one organization?

Yes. One personal account can belong to many organizations, such as your employer, an open-source project and a club. You switch between them using the account context menu, and each organization controls its own repositories and permissions.

Why doesn't my organization show on my profile?

Organization membership is private by default. On the organization's People page you can make your own membership public, and the organization's logo then appears on your profile.

GitHub Organizations Exercises

Answer each one and check it instantly. If you get stuck, open the hint before the answer.

Fill in the blankseasy

Complete the CODEOWNERS line so the docs team owns the docs folder.

/docs/ @acme/
Multiple choiceeasy

Why use an organization instead of a personal account for a company's code?

Multiple choicemedium

Which repository role lets someone push branches and merge pull requests?

Multiple choicemedium

What is an outside collaborator?

Multiple choicehard

What advantage do organization rulesets have over per-repository branch protection?

GitHub Organizations Quiz

5 questions to check what you learned.

  1. How many owners should an organization have at least?

    • Two
    • One
    • Ten
    • Every member

  2. How do you notify a whole team on a pull request?

    • Email each person
    • Mention it, such as @acme/frontend, or request its review
    • Add a label
    • Star the repository

  3. What does a nested team inherit?

    • The parent team's repository access
    • Nothing
    • The organization's billing
    • Its parent's members

  4. What should the organization's base permission usually be?

    • Admin
    • Write
    • Owner
    • The lowest that works, such as Read or None

  5. Someone leaves the company. Besides removing them from the organization, what should you check?

    • Their profile picture
    • Automation using their personal tokens or keys, which should be replaced
    • Their stars
    • Their public gists

Related GitHub topics

18SecurityKeep your repositories safe with branch protection, Dependabot, secret scanning, code scanning, collaborator permissions and a security policy.09Code ReviewReview pull requests on GitHub: comment on lines, suggest changes, approve or request changes, and give feedback that helps.02RepositoriesCreate a repository on GitHub, write a helpful README, choose public or private, and add a .gitignore and licence.
Esc
↑↓ to navigateEnter to open