GitHub Organization Best Practices: Single vs. Multi GitHub Enterprise Organizations

I. Introduction

• Choosing between a single or multiple GitHub Organizations is a strategic decision.
• The best approach depends on your specific needs and team dynamics.
• Enterprises can have one or more organizations.
• Each organization can have a distinct set of members.
• Each organization has its own repositories.

II. Factors to Consider

• Team Structure and Autonomy:
  • Independent teams: Multiple organizations may be better.
  • Collaborative teams: A single organization might be preferable.
• Access Control and Permissions:
  • Granular control needed: Multiple organizations.
  • Simpler control needed: Single organization.
• Billing and Licensing:
  • Simplified billing: Single organization.
  • Departmental/project-based cost allocation: Multiple organizations.
• Repository Visibility:
  • Easy sharing: Single organization.
  • Strong isolation: Multiple organizations.
• Governance and Policy:
  • Centralized policies: Single organization.
  • Different policies for different projects: Multiple organizations.
• Scalability and Growth:
  • Stable structure: Single organization.
  • Evolving structure: Multiple organizations.
• Discovery:
  • Easy discovery: Single organization.
  • Challenging discovery: Multiple organizations.

III. Strategies

A. Single Organization

• Pros:
  • Simplified administration and billing.
  • Easier cross-team collaboration and code sharing.
  • Centralized governance and policy enforcement.
  • Improved project discoverability.
  • Easier onboarding.
• Cons:
  • Complex management with many teams/repositories.
  • Requires careful planning of teams/permissions.
  • Less isolation between teams.
• Best For:
  • Small/medium collaborative companies.
  • Companies with centralized IT/governance.
  • Projects with frequent cross-team interaction.

B. Multiple Organizations

• Pros:
  • Stronger isolation.
  • More granular control.
  • Easier to manage complex structures.
  • Independent billing/licensing.
  • Better for strict compliance.
• Cons:
  • Increased overhead.
  • Can hinder collaboration.
  • Complex billing.
  • Difficult project discovery.
• Best For:
  • Large enterprises.
  • Companies with independent teams.
  • Projects with strict security/compliance.
  • Departmental cost allocation.

C. Hybrid Approach

• Primary organization for most projects.
• Separate organizations for sensitive projects/acquisitions.

IV. What's in an Organization?

• Repositories
• Copilot access
• Projects
• Packages
• Discussions
• Teams
• Security & org level insights
• Audit Log

Note: Distinct organizations are NOT needed to limit repository access. Repository access can be limited via base user permissions and Teams.

V. Key Considerations (for either approach)

• Naming Conventions: Clear and consistent naming.
• Team Structure: Carefully plan and map to organizations.
• Access Control: Robust model using teams and permissions.
• Automation: Automate administrative tasks.
• Documentation: Maintain clear documentation.

VI. Best Practices

Start with only ONE organization.

• Why start with only one organization?

  • Individual organizations are intended for users who work together, i.e., whole engineering teams and their cross-functional counterparts.
  • Access to and permissions on repositories are managed with base member permissions and GitHub Teams, so in many cases a company will only need one organization.
  • SCIM is only available at the organization level.
    • Using SCIM across multiple organizations requires unique SSO & SCIM configurations on each organization, so having only one organization simplifies setup.
  • For GitHub Enterprise Managed Users:
    • User management is handled differently, with SCIM and SSO configurations managed at the enterprise level rather than the organization level.
    • This allows for centralized user management across multiple organizations within the enterprise.

• When does it make sense to create more than one organization?

  • Two main use cases:
    • Companies with distinct business entities whose engineering teams operate independently.
      • Example:
        • Company A acquires Company B.
        • Each company has a unique product line and different engineering teams.
        • The engineering teams rarely interact or work together on the same project.
        • Deploys are separate.
    • Companies with divisions/departments that operate independently.
      • Example:
        • Company A has an engineering team that works on their primary product.
        • They also have an R&D team that works on highly sensitive code.
        • The two teams rarely interact or work together on the same project.
        • None of the R&D conversations in PRs, Issues, or Discussions need to be visible to the engineering team working on the primary product.
    • Note: For Enterprises with multiple organizations, if the organizations need to collaborate on projects (for example, share internal tooling), this can be done using Internal Repositories.

• To create an organization, go to:

  • Enterprise → Organizations (left sidebar) → New organization (button upper right)
  • GitHub Docs:
    • Creating a New Organization

• Set base user permissions to Read.

  • Why set permissions to Read?
  • When should base user permissions be set to No Permissions.

• To set base user permissions, go to:

  • Enterprise → Settings → Repositories (landing page) → Base Permissions (top of the page) OR
  • Organization → Settings → Member Permissions (left sidebar) → Base Permissions (top of the page)
  • GitHub Docs:
    • Setting Base User Permissions on an Organization

VII. Teams

• Teams are groups of organization members.
• Teams are used grant/control repository and organization access permissions.
• Teams are used for communication within GitHub (e.g., notifying a team that a particular PR needs attention).
• For GitHub Enterprise Managed Users:
  • Teams can be synchronized with Identity Provider (IdP) groups, allowing for centralized management of team memberships and permissions.
  • This synchronization ensures that changes in the IdP are automatically reflected in GitHub, simplifying user management.

VIII. Best Practices

• Organize members into teams that reflect your company's internal structure.
  • Teams are used for managing repository access, but they are also used for communication and can be used to filter repositories and security alerts (for customers using Advanced Security).
  • Given this, it is important to set up teams that reflect your company or engineering team's structure.
  • Note: In addition to teams that reflect your company structure, you can also create teams that grant permissions only.
    • Example:
      • Your company's engineering organization has a dev team called, "DevTeam1," that includes a team lead, four developers, a QA engineer, and a scrum leader.
      • The team lead should have admin permissions on three repository, but everyone else should only have read or write permissions on those repositories.
      • Create a GitHub team for DevTeam1 that can be used for communication. Assign repos and give the team Read access.
      • Create another GitHub team for the developers on DevTeam1. Assign repos and give the devs Write access.
      • Finally, create one more GitHub team for the team lead. Assign repos and give the team lead Admin access. (Alternatively, give the team lead admin access individually, via the People tab).
  • Note: Teams can be synced to IdP groups.
  • To create teams, go to:
    • Organization → Teams → New team (button to the right)
    • GitHub Docs:
      • Teams
      • Creating a Team
      • Team Sync

IX. Quick Summary

One single (large in some cases) org is simpler—easier to manage, everyone can see everything, and billing's a snap. Great for smaller companies or teams that work closely together. But it can get messy if you have lots of separate teams, and managing permissions can be tricky.

Multiple orgs are better for big companies with teams that don't interact much, or if you need really strict security. Each org is totally separate, with its own members and repos. It's good for splitting up costs too, but it does mean more work to manage, and teams might not share stuff as easily.

Basically, if you can, start with just one org. It’s simpler, and you can always split it up later if you need to. Think about what your teams need now and what they might need in the future.

You can also do a mix of both with a main org for most things and smaller orgs for really sensitive stuff.

Key things are naming your orgs well, planning out your teams and who gets to see what, tightening security, and automating tasks to make it easier. You should also keep clear notes on how everything is set up.

X. Q&A

In Summary

GitHub Organizations offer a top-level namespace, and repositories are the primary way to divide code. Teams provide logical grouping and access control. GitHub Projects help manage work within those repositories. If you need strong isolation, multiple organizations are the answer. If your "projects" are more related, a single organization with well-organized repositories and teams is usually the way to go.

XI. Recommendation

• Start with a single organization if possible.
• Evaluate needs and factors.
• Consult with GitHub support/expert

Decision process

Part 1: Initial Decision Points

graph LR
    A[Start] --> B{Do you have independent teams?}
    B -->|Yes| C{Do you need strong isolation?}
    B -->|No| D{Do you have collaborative teams?}

Part 2: Independent Teams Path

graph LR
    C{Do you need strong isolation?} -->|Yes| E[Multiple Organizations]
    C -->|No| F{Do you need granular control?}
    F -->|Yes| E
    F -->|No| G[Single Organization]

Part 3: Collaborative Teams Path

graph LR
    D{Do you have collaborative teams?} -->|Yes| G[Single Organization]
    D -->|No| H{Do you need simplified billing?}
    H -->|Yes| G
    H -->|No| I{Do you need departmental/project-based cost allocation?}
    I -->|Yes| E[Multiple Organizations]
    I -->|No| J[Single Organization]

Part 4: Departmental/Project-Based Cost Allocation Path

graph LR
    I{Do you need departmental/project-based cost allocation?} -->|Yes| E[Multiple Organizations]
    I -->|No| J{Do you need easy sharing?}
    J -->|Yes| G[Single Organization]
    J -->|No| K{Do you need strong isolation?}
    K -->|Yes| E
    K -->|No| G[Single Organization]

Part 5: Strong Isolation Path

graph LR
    K{Do you need strong isolation?} -->|Yes| E[Multiple Organizations]
    K -->|No| L{Do you need centralized policies?}
    L -->|Yes| G[Single Organization]
    L -->|No| M{Do you need different policies for different projects?}
    M -->|Yes| E[Multiple Organizations]
    M -->|No| G[Single Organization]

Part 6: Different Policies Path

graph LR
    M{Do you need different policies for different projects?} -->|Yes| E[Multiple Organizations]
    M -->|No| N{Do you have a stable structure?}
    N -->|Yes| G[Single Organization]
    N -->|No| O{Do you have an evolving structure?}
    O -->|Yes| E[Multiple Organizations]
    O -->|No| G[Single Organization]

Part 7: Evolving Structure Path

graph LR
    O{Do you have an evolving structure?} -->|Yes| E[Multiple Organizations]
    O -->|No| P{Do you need easy discovery?}
    P -->|Yes| G[Single Organization]
    P -->|No| Q{Is challenging discovery acceptable?}
    Q -->|Yes| E[Multiple Organizations]
    Q -->|No| G[Single Organization]

Part 8: Challenging Discovery Path

graph LR
    Q{Is challenging discovery acceptable?} -->|Yes| E[Multiple Organizations]
    Q -->|No| R{Do you need centralized policies?}
    R -->|Yes| G[Single Organization]
    R -->|No| S{Do you need different policies for different projects?}
    S -->|Yes| E[Multiple Organizations]
    S -->|No| G[Single Organization]