Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Repositories and Collaboration

Organizations and Teams

Create a GitHub organization, understand owners and members, build teams with nested structure, set base permissions and defaults, and use a .github repository for shared files.

A personal account is fine for your own projects. As soon as several people work together, or a project should outlive any one person, you want an organization: a shared account that owns repositories, has members, and can be managed centrally. Organizations are free to create, and the free plan covers unlimited public repositories (private features depend on the plan).

Creating an organization

Click + > New organization, choose a plan, pick a name (it becomes github.com/<org>), a contact email and whether it belongs to you personally or a business. You become the first owner. Then invite people by username or email.

You do not sign in as the organization; you sign in as yourself and act within it. Everything you do there is recorded under your own identity, which is why the audit log (organization settings) can tell who changed what.

Organization roles

Role Description
Owner Full control: billing, members, settings, deleting the organization. Keep owners few.
Member Default role. What a member can do in repositories depends on the base permission and team access.
Billing manager Manages payment only, with no code access.
Security manager Can manage security alerts and settings across repositories without being admin everywhere.
Outside collaborator Not a member, but has access to specific repositories.

The base permission (Settings > Member privileges) is the minimum role every member gets on all repositories: No permission, Read, Write or Admin. A common choice is Read or No permission, and then grant more through teams. You can also restrict who may create repositories, change visibility, delete repositories and fork private repositories.

Teams

A team is a named group of members with shared access and a shared mention handle such as @octo-org/backend. Create one under Teams > New team. Settings that matter:

  • Visibility: Visible (all members can see and @mention it) or Secret (only its members and owners).
  • Parent team: teams nest. A child team inherits its parent's repository access, and mentioning the parent notifies descendants. For example engineering > backend and frontend.
  • Repository access: add repositories to the team with a role each (Read to Admin, or a custom role).
  • Maintainers: team members who can add or remove other members without being owners.
  • Code review settings: automatic review requests, with options like round-robin or load balancing, so pull requests are assigned fairly.
  • Sync with an identity provider: on plans with single sign-on, team membership can follow groups in your company directory.
flowchart TD
  O["Organization: octo-org"] --> E["Team: engineering<br/>Write on all code repos"]
  E --> B["Team: backend<br/>Write on api, worker"]
  E --> F["Team: frontend<br/>Write on web, design-system"]
  O --> D["Team: docs<br/>Triage on all repos"]

A nested team inherits access from its parent and can add repositories of its own.

JS Stand-in: effective permission of a member

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

No output.

The highest applicable role always wins. That means you can raise someone through a team, but you cannot lower below the base permission with a team, which is why the base is best kept low.

The organization profile and the .github repository

Organizations have their own profile page. A public repository named .github in the organization provides defaults that apply to every repository that does not define its own:

  • Community health files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md), issue and pull request templates, and workflow templates in workflow-templates/.
  • A profile/README.md file that is displayed on the organization's profile page (a private .github-private repository can add a members-only profile).

This is an efficient way to keep dozens of repositories consistent.

JS Stand-in: default health files

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

No output.

Good habits

  • Have at least two owners, and require 2FA for all members (Settings > Authentication security).
  • Keep the base permission at Read or lower; use teams for everything else.
  • Name teams after responsibilities (backend, docs), not individuals.
  • Review members, outside collaborators, installed apps and deploy keys every quarter.
  • Use the audit log when you need to answer "who changed this setting?".
  • Transfer important repositories into the organization (Settings > Transfer) so they do not depend on one person's account; GitHub redirects the old URLs.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. A member is in two teams with Read and Write on the same repository, and the base permission is Read. What is the effective role?

    The highest permission applies.
  2. 2. What does a nested (child) team inherit from its parent?

    Child teams inherit the parent team's repository access and can add more of their own.
  3. 3. Where do you put CONTRIBUTING.md so that it applies to all repositories in an organization that lack their own?

    The public .github repository supplies defaults for community health files.

Summary

  • Organizations hold repositories centrally; you act within them as yourself.
  • Roles: owner, member, billing manager, security manager and outside collaborator; the base permission is the floor for all members.
  • Teams group members, can nest, and are the preferred way to grant repository access.
  • A .github repository supplies shared community files and profile content.

Next: Pull Requests: The Basics