Strategies for using organizations in GitHub Enterprise Cloud
Within GitHub Enterprise Cloud (GHEC), organizations are shared accounts where your users collaborate across many projects at once, with sophisticated security and administrative features. It’s important to plan your structure in advance to avoid creating unnecessary silos and increase administrative overhead. A good structure will facilitate collaboration and discovery while reducing administrative overhead.
We’ll hear from Philips on why they chose to use a single organization—with a small exception—for their GitHub Enterprise architecture, and from Fidelity, on why they chose a common, but slightly more complex architecture.
In this guide, you will learn:
Why GitHub recommends using the fewest organizations possible to meet your business needs
Common business considerations for using multiple organizations
Why overly indexing GitHub organizations to corporate structure can be problematic
How to choose the organizational structure that’s best for your enterprise, including examples of some possible models
What is the recommended number of organizations?
Some GHEC customers use a single organization to collaborate on all of their content. Others choose to create multiple organizations in their enterprise account because they require full separation of their content to meet business requirements, such as:
Legal or business distinctions between sets of content, users, etc.
Data classification or regulatory requirements
Mergers, acquisitions, divestitures, and other commercial changes
The ability to provide a test/sandbox area for their users to try out new features, complete training exercises, etc.
In general, we recommend creating the fewest possible organizations within your enterprise to accommodate your business needs. If possible, use just one. Each organization requires its own administration and configuration, so additional organizations create additional overhead. Organizations are also designed to maintain separation from each other, so they create silos by definition and can inhibit collaboration and impede an innersource culture (wherein open source principles are applied internally). Make sure you are not using organizations to create separations where you could use teams and repository permissions instead.
Corporate structure and organizations
We recommend that you don’t overly index your GitHub organizations to your corporate structure.
When configuring GHEC, you might initially think it's best to create a separate organization for each project or department to manage permissions and minimize notifications. We don’t recommend this. It restricts the flexibility of your organizational structure and may lead to more complex challenges in the long run.
One reason for this is that corporate structures can change frequently, sometimes with significant disruption to the status quo and little notice. Your GHEC configuration should gracefully handle corporate reorganizations without affecting your GitHub organizations and creating downstream work, such as re-pathing integrations and updating external links. Additionally, indexing your organization structure to your corporate structure increases siloed conversations and expands management burden.
Instead, consider using GitHub teams within a single organization to assign roles and permissions. Teams and users within the same organization can easily find each other's content, ask questions, and mention one another. This becomes more complicated if they are spread across multiple organizations. If a team needs access to more than one organization, the team must be created in each organization and mapped to the appropriate identity provider group. Administrators quickly become overwhelmed with requests to add and manage users in multiple organizations simply to view content or ask a question, thereby negating many of the advantages of keeping the organizations separate from the beginning.
Finally, having an organization for every project increases the burden of managing integrations. GitHub Apps are installed in organizations, so enterprises with many organizations must install and manage each of their integrations in each of their organizations. Also, note that there is a limit of 100 GitHub App installations per organization.
Choosing the organizational structure best for your enterprise
Below we’ll dive into three common models successfully adopted by GitHub Enterprise Cloud customers that effectively utilize as few organizations as prudent for their business.
Model 1: Single organization
In this model, a single organization is used for all or the vast majority of repositories. Many small- to medium-sized organizations (less than 5,000 developers) use this approach to manage their GitHub environment.
Most users of this model set their organization’s base permissions to none. This requires all users to be explicitly added to all repositories in order to view them and/or propose changes. By itself, this approach creates silos, greatly limits visibility, and actively prevents innersource. To counter this tendency, we recommend that you use teams to ensure visibility. For example, you can create an “all members” team and add it to repositories that are open to collaboration. You can even go as far as to have this type of team automatically added to all repositories by default, and then establish an exception process for when repositories must truly be kept on a need-to-know basis.
Exceptions
Slight variations on this model exist to handle extenuating circumstances. For example, you might maintain one or two “top secret” organizations for projects that must be kept completely separate from all other work, like projects for highly sensitive customers. Still, the overwhelming majority of your work takes place in a single organization.
Similarly, you might use a separate organization to segment repositories managed by teams in particular locations to address concerns around intellectual property laws.
We moved to GitHub so we could unify our teams on a single platform to encourage innersource. We have teams distributed across the globe, and previously they were each using their own system, which made it incredibly hard for us to work together. We had to handle different systems, policies, teams, etc. Now, we have all of our developers and our internal code in a single GitHub organization where we set our internal repositories to read access by default, which makes it easier to discover and reuse code.
At the same time, we have additional GitHub organizations for open source collaboration and for testing. This allows us to keep distinct boundaries and permissions, while still enjoying the simplicity and visibility provided by a single organization for the majority of our software development.
Model 2: Red-green-sandbox-archive
The red-green-sandbox-archive model utilizes two primary organizations and a sandbox. We’ll explain how each piece works below.
Green organization
The green organization serves as the primary collaboration space for your developers, with about 90% of your repositories residing here. You’ll want to set the base permissions to “write” to promote innersource and empower users to propose changes to repositories. At the same time, you will use branch protections (discussed in a later guide in this module) on repositories in the green organization to ensure that users can only propose changes, and that those proposed changes will go through the defined code review and approval process to be accepted.
You will then grant higher-level permissions to repositories through teams, which can be viewed in each team’s repository page. With most activity happening in the green organization, the burden of managing teams and integrations is minimized.
Red organization
The red organization is for repositories that must be kept on a need-to-know basis. Set the organizations’ default permissions to none to require that teams be explicitly added to the repositories to read them or propose changes.
You should have a defined process for creating repositories and teams in this organization to prevent unnecessary, self-imposed constraints.
Sandbox organization
A sandbox organization provides a shared space where any user can create and experiment with repositories. This space is more visible and encourages collaboration more effectively than using individual personal repositories. Such an organization is especially important if you configure GHEC to prevent developers from creating personal repositories.
If you decide to use a sandbox organization, you’ll need to define a process for moving work from the sandbox into the green or red organizations to ensure experiments can transition into more formal management.
Archive organization (optional)
Finally, the optional archive organization contains repositories that are no longer actively maintained. While any repository can be archived, making it read-only for all users, these archived repositories can remain in their existing organizations. Some companies prefer to transfer ownership of these archived repositories to a separate organization, leaving their other organizations for active work. Note that choosing to do this changes the owner/name syntax of the repositories and may make finding the repository in GitHub more challenging if the user expects it to be in the original organization.
At first, we were tempted to mirror the Fidelity product model using GitHub organizations, which would have led to a large number of organizations. We quickly realized we’d run into difficulties from an access and control management perspective and scaling challenges on innersource, enablement, onboarding and support.
We ended up using the red-green-sandbox-archive, which provided us with an open, visible model that would promote innersource, re-use, and discovery, while also giving us the security and compliance controls we needed for our highly-confidential and regulated code.
To enable wider collaboration and innovation, and to support hackathon style events, developers can create repos in the sandbox organization with minimal policy and restrictions. They can also fork projects in the green organization into their own personal user space to collaborate with others and then submit a pull request to merge the changes back to the main project. This really creates a frictionless innersource ecosystem and makes it easy for someone to discover and contribute.
Model 3: Portfolio company
There are a few scenarios in which the red-green model may not adequately match your company’s internal structures.
For example, very large companies with tens of thousands of employees that are divided into relatively static business units, like a global bank consisting of retail banking, personal investments, capital markets, and insurance divisions, may find this model insufficient.
Also in this camp are portfolio companies with operating units that function independently of one another, like a media company consisting of broadcast networks, production studios, streaming services, and interactive games companies. These companies may also experience regular mergers, acquisitions, and divestitures.
For a very large company we recommend mapping your GHEC organization structure to your highest-level corporate division. These will generally be divisions one level below the CEO and static in nature because organizations typically happen within these divisions, leaving the top level structure as-is.
In a portfolio company, organizations should be mapped to each business entity. Organizations can be transferred from one enterprise to another, easing the burden of managing a merger or divestiture.
If possible, we recommend keeping a single organization per portfolio company or major business division. This is essentially multiple implementations of the single organization strategy described above. At most, we recommend implementing a minimal red-green structure for each major division. If you go down this path, consider implementing a single sandbox across all units and keeping archive repositories in the primary organization. This will help minimize the number of active organizations to manage.
A note on open source projects for portfolio companies: Open source projects should be kept in a dedicated organization, separate from the corporate organization(s). Otherwise you can run into security boundary issues, particularly when you use outside collaborators. If you are using an Enterprise Managed User (EMU) environment, this may require having separate enterprise accounts given the constraints.
Creating and managing organizations in your enterprise account
Once you’ve determined the appropriate structure for your organizations, enterprise owners can manage the organizations that are owned by the enterprise account using a few different options: creating a new organization, inviting or transferring an existing organization (enterprises not using EMUs only), and managing membership and ownership of organizations.
Create a new organization
Creating a new organization in your enterprise will provide you with a new, separate container for repositories, projects, documentation, and collaboration. Naming for organizations must be unique across all of GitHub.com, regardless of its enterprise ownership. The enterprise account name is not included in the organization URL or path.
Enterprise owners who create an organization owned by the enterprise account automatically become organization owners. You can select additional organization owners during the creation process.
Inviting or transferring an existing organization
Note: This option is only available to enterprises not using EMUs, because EMU enterprises restrict the ingress and egress of non-enterprise content without the use of migration tooling.
If there is an organization that already exists on GitHub.com that you’d like to bring into your enterprise account, you can transfer or invite it into your enterprise account. Depending on the existing organization’s ownership, you’ll need ownership or approval from the current enterprise owner (if it’s part of an enterprise) or organization owner (if it’s a stand-alone organization). You, as the receiving enterprise owner, must also give a final approval for the transfer once the current owner accepts.
A number of important considerations apply when transferring an external enterprise into your enterprise, which are outlined in depth in the documentation. The most crucial of these to keep in mind is that you will need sufficient user licenses in your enterprise account to accommodate any additional unique users in the incoming organization.
This option is useful for mergers and acquisitions, migrations, and upgrade scenarios where part of your organization was using a non-enterprise GitHub plan previously. Depending on your longer-term strategy, you may want to keep the transferred organization separate, or further transfer the repositories into other organizations.
Managing membership and ownership of organizations
As an enterprise owner, you can add yourself as an organization owner or member to any organization in your enterprise, as long as that organization is not managed by organization-level SAML and SCIM for its membership. This can be helpful if organization owners leave or become unavailable or you otherwise need access as one of these roles. You can also use this interface to remove yourself from these roles if you no longer need the access.
For organizations managed with SAML and SCIM, be sure to use the identity provider for provisioning instead to avoid being inadvertently deprovisioned through automation.
Up next: Configure your GitHub Enterprise Cloud enterprise settings and policies
Now that you can make an informed decision about when and how to use more than one organization within your enterprise account, it’s time to take a look at the key settings you’ll need to configure, at both the enterprise and organization levels.