Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Administration and API

Organizations, Teams, Roles and CODEOWNERS

Manage who can do what on GitHub: organizations, teams, repository roles, outside collaborators, custom roles and CODEOWNERS review rules, with a CODEOWNERS matcher you can run.

A personal repository has one owner and some collaborators. A company or open-source project needs more structure: many people, many repositories, and different levels of trust. Organizations are GitHub's answer. They let you manage people and permissions once, then apply them to every repository the organization owns.

Accounts and organizations

Every person has a personal account. An organization is a shared account that owns repositories but is not a person: you cannot sign in as it. People join as members, and the organization has its own settings, billing, audit log and security policies. Create one from the + menu -> New organization; free plans exist for open-source and small teams.

Organization roles (for people):

Role Can
Owner Everything: billing, members, settings, deleting the organization
Member Access what teams and repositories grant; create repositories if allowed
Billing manager Manage payment only
Outside collaborator Access specific repositories without being a member

Keep at least two owners so losing one account never locks you out, and keep the owner list short.

Teams

A team is a named group of members, such as backend, docs or release-managers. Teams can nest (engineering -> engineering/backend), and child teams inherit the parent's repository access. Instead of granting access to 15 individuals on 20 repositories, you grant a team a role on the repository once. When someone joins or leaves a team, their access follows. Teams can also be @mentioned (@my-org/backend) in comments to notify everyone, and can be requested as reviewers.

Repository roles

Access to a repository comes from a role, assigned to a user or a team:

Role Typical capabilities
Read View, clone, open issues and discussions
Triage Read plus manage issues and pull requests (labels, assign, close), without code write access
Write Triage plus push to branches and merge pull requests
Maintain Write plus manage some repository settings, without destructive or sensitive actions
Admin Full control, including settings, collaborators and deletion

Give people the lowest role that lets them do their job; triage is perfect for community moderators. Enterprise plans offer custom repository roles that combine individual permissions (for example "write plus manage Actions secrets"). Organization-wide base permissions (Settings -> Member privileges) set the default access every member has to all repositories; "No permission" is the safest default for private work.

Outside collaborators are invited per repository, which suits contractors. Deploy keys give one machine read (or read/write) access to one repository, and fine-grained personal access tokens and GitHub Apps let automation act with narrow, explicit permissions instead of a person's full account.

flowchart TD
  O["Organization"] --> T1["Team: backend"]
  O --> T2["Team: docs"]
  T1 --> R1["Repo: api (Write)"]
  T1 --> R2["Repo: infra (Read)"]
  T2 --> R3["Repo: handbook (Maintain)"]
  C["Outside collaborator"] --> R2

Teams carry repository roles; outside collaborators attach to a single repository.

Securing the organization

Useful settings under Settings of the organization:

  • Require two-factor authentication for all members. This is the single most effective account-security control.
  • SAML single sign-on (enterprise) ties access to your identity provider.
  • Member privileges: restrict who can create public repositories, fork private ones, or delete repositories.
  • Third-party and OAuth app access: review and restrict which apps can read your data.
  • Audit log: a searchable record of who changed what and when (settings, permissions, secrets, deployments).

CODEOWNERS: review rules in the repository

Roles control who can push; CODEOWNERS controls who should review. A file named CODEOWNERS in .github/, the root or docs/ maps path patterns to owners (users or teams). When a pull request touches matching files, GitHub automatically requests review from those owners. With the branch rule "Require review from Code Owners" (rulesets) their approval becomes mandatory.

TEXT
# Everything defaults to the maintainers
*                   @my-org/maintainers

# Documentation
/docs/              @my-org/docs
*.md                @my-org/docs

# Workflows and security-sensitive files need the platform team
/.github/workflows/ @my-org/platform
/SECURITY.md        @my-org/platform @mona

# Frontend code
/web/src/**/*.tsx   @my-org/frontend

Rules: the syntax is similar to .gitignore; the last matching pattern wins, so put general rules first and specific ones later; a path with no owner after it removes ownership. Owners need write access to the repository to count.

The stand-in below implements that "last match wins" logic with simplified patterns. It is our own helper, and GitHub's matcher handles more gitignore details.

JS Stand-in: CODEOWNERS matcher (simplified)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You want community moderators to label and close issues but not push code. Which role fits?

    Triage grants issue and pull request management without write access to code.
  2. 2. Why grant repository access to teams instead of individuals?

    One change in a team's membership affects every repository the team can access.
  3. 3. In a CODEOWNERS file, which rule applies when several patterns match a path?

    Like gitignore, later lines override earlier ones, so put general patterns first.
  4. 4. What is the most effective organization-wide account-security setting?

    Mandatory 2FA greatly reduces the chance that a stolen password leads to a compromised organization.

Summary

  • Organizations own repositories and centralize people, billing, policy and the audit log.
  • Teams (which can nest) receive repository roles: read, triage, write, maintain, admin.
  • Use least privilege, outside collaborators for contractors, and require 2FA.
  • CODEOWNERS maps paths to reviewers; the last match wins, and rulesets can make owner review mandatory.

Next: Branch Protection and Rulesets