Build what's next on GitHub, the place for anyone from anywhere to build anything.
Join us October 28-29 in San Francisco or online for GitHub Universe, our flagship developer event uniting people, agents, and the world's code.
Learn how you can structure your enterprise to get the most value out of GitHub and provide the best experience for your developers!
When a new customer starts using GitHub Enterprise, one of the first questions they usually ask is: How do we structure the organizations within our enterprise?
Even experienced GitHub administrators frequently reevaluate and seek guidance on how they should group organizations and teams within their enterprise.
Why? An effective structure is crucial in maximizing the value of GitHub and enhancing the experience for you and your developers. Enterprise structural decisions can determine whether you accelerate with DevSecOps and Innersourcing principles that enable efficient workflows, or remain stuck in silos and forfeit potential productivity gains.
The purpose of this post is to provide you with a set of guidelines to help you design the most suitable organization and team structure for your enterprise and to effectively align GitHub with your company’s culture.
First, let’s take a step back and talk about why you should focus on culture to begin with.
The term DevSecOps has been around for quite some time now. While exact definitions for it differ, DevSecOps generally stands for taking a holistic approach to the Software Development Life Cycle (SDLC) by building a culture of shared responsibility within a project team to deliver value in a fast, secure manner.
By using GitHub, you can expand the scope of collaboration beyond just one or a few teams. GitHub’s goal is to enable collaboration throughout your entire enterprise. To achieve this, you can leverage a strategy known as “innersource,” which takes all the values and lessons learned from the open source community and puts them behind the safe walls of your enterprise.
The success of innersourcing shows. According to a recent Forrester report, GitHub Enterprise can produce up to a 433% return on investment over three years. The ROI is mostly achieved by increasing your developers’ productivity up to 22%. Philips shared that 70% of their developers reported an innersource approach that improved their development experience. For a better understanding of how innersourcing works, check out this brief on how to accelerate innovation with innersource.
The answer to setting up an innersource-friendly developer platform could be simple: let anyone see and propose changes to any content, anywhere! In GitHub terms, this would mean using a single organization with the default repository base permissions set to read or write. Done!
But enterprises usually don’t work that way. There are many requirements that make access control and user permissions a challenge, such as the need to protect valuable intellectual property, stay compliant with audit or regulatory requirements, guard top-secret code and data, and follow security protocols. Additionally, it can be a challenge to manage the opinions and desires of the numerous individuals who make up your enterprise.
Finding the right balance between these requirements and fully realizing the innersourcing values described above can be hard, but the organizational structure of your GitHub enterprise and the flexibility allowed by the platform can help in reaching this sweet spot between compliance and efficiency. So, let’s see what you can do to find it.
Let’s define a GitHub organization by referencing our “Book on GitHub Enterprise Cloud Adoption”:
Organizations are the “owners” of shared repositories, discussions, and projects. They let administrators set more granular policies on repositories belonging to the organization and user behavior within the organization. […]
Organizations also serve as a roll-up mechanism for reporting. […]
Consumption-based services, such as GitHub Actions and Codespaces, are reported at both the repository and organization level. Spending limits on these services can be set on a per-organization basis.
In other words, a GitHub organization is a grouping mechanism for repositories, teams, projects, settings and controls that, critically, keeps these things completely separate from each other.
To summarize, every organization is a sort of intentional “silo,” with its own policy and content boundaries, and therefore administrative overhead. However, it is also the primary method of grouping and enforcing controls on resources where these divisions are necessary for your business.
Again, referencing the “Book on GitHub Enterprise Cloud Adoption”:
GitHub Teams group users of common projects or specialized skills, they are often the mechanism for providing role based access to collections of repositories. […]
A team belongs to an organization, and an organization can have many teams. There are several ways teams help establish culture within your enterprise, for example, through access controls, communication, such as discussions, work and knowledge sharing in code reviews, and roles.
There is a lot of flexibility when it comes to creating teams, and whether you choose to create only a few broad teams or also many finer-grained teams is entirely up to you. You can centralize team creation to just your administrators, or you can allow anyone who is a member of your organizations to create their own teams for collaboration and communication if you prefer. For those in need of additional structure in their team permission inheritance, you can even nest teams. Nested teams create hierarchy for inherited access in child teams from their parent team, although remember that they can also add complexity in tracking permissions models, so use them wisely!
The general recommendation is to establish teams based on areas of responsibility, communities, and common projects or product families. Also important to note: team membership may be managed through groups if using supported identity providers for easy management (with team synchronization or group SCIM, depending on your access model.)
So, how should you go about finding that sweet spot between maximizing innersourcing and conforming with all the desired controls? We can start by establishing some universal truths no matter your situation. This will help establish guard-rails before we have a deeper look at the impacts on individual GitHub features.
This shouldn’t come as a surprise since innersourcing is one of the main topics of this post. Innersourcing thrives on wide visibility and collaborative capabilities.
So, when you think about how to structure your organizations, rather than coming from the perspective of “How can we best protect our resources?”, take the stance of “How can we maximize collaboration, given our required controls?”. This mindset will make it easier for you to find creative solutions or maybe even question existing restrictions rather than accepting them for hard truths.
Often enough, strict controls will not apply to all of your developers or projects. Thus, it’s important to target the right resources for required controls and give more freedom to the rest. Adopting this mindset will not only help you prioritize enterprise-scale efficiency over individual desires, but add more weight to the importance of streamlining processes and tools to avoid wild growth and shadow-IT approaches.
For instance, imagine an individual development team had its own organization. The ability to freely adjust settings to meet their needs and install applications seems to provide a lot of flexibility. However, the efficiency gains that result from standardization between policies and comprehensive collaboration across repositories (for example, repository rulesets, reusable workflows, and code security to name a few) are even greater.
“Try to have as few organizations as possible to meet your requirements”—this is the mantra you might have heard from GitHub and the first conclusion we drew in the section on organizations. Of course, there are ways to overcome the complexities of many organizations, such as having a mature collaboration culture, using internal repositories, or simply adding users to multiple organizations. Nonetheless, more organizations will induce additional work and overhead for administrators.
Automation around GitHub structure for example, through the GitHub Terraform Provider, can help to reduce that administrative burden somewhat. Of course, it requires someone to create and maintain those automations. And even the most sophisticated automation probably won’t scale indefinitely, so a good strategy around when and why you will create new organizations or work with existing ones is still wise from the outset. You may also want to take advantage of GitHub Apps, which provide an increased rate limit for GitHub Enterprise customers to help support scalability and can be installed at the organization level to help support even multi-org setups.
In addition to the technical considerations, don’t underestimate the impact that bridging multiple organizations can have on your developers’ feeling of belonging. Being a member of one large group with frequent interactions is distinct from being a member of several smaller groups.
In summary, the impact of fewer organizations can vary significantly, depending on the technical capabilities, cultural readiness for collaboration, and size of your enterprise. However, the generalization that it leads to less siloing is always true to some extent.
Adding new organizations is generally easier than removing or merging existing ones.
Merging organizations requires finding a common ground in terms of policies, settings, and ownerships; this may result in developers losing some freedom they were accustomed to. Conversely, creating a new organization provides developers with all the freedom to structure it according to their requirements.
Therefore, having fewer organizations from the start increases your flexibility in reacting to changing requirements in the future.
Building organizations around existing micro-structures like business units or even teams is rarely a recipe for success. It can codify the silos that you are trying to overcome and make it difficult to accommodate structural business changes (and we know those can happen frequently with little prior notice.) Instead, focus on what needs to be managed within products (for example, source code, release cycles, communication, and access control) and determine where there is overlap. Grouping organizations based on shared responsibilities can help streamline operations, address any gaps or similarities in workflows, and provide a holistic view on the structure of your development process.
As an example, consider two teams in a microservice application: one is the producer of a service and the other is the consumer. Although two separate teams and potentially in different business units, both teams share ownership and the responsibility to find the right architecture for the service communication. As a result, the teams must collaborate if the entire project is to be successful. So, in terms of GitHub, if you put the two teams into different organizations to accommodate for the existing structure, there would be no easy way to encourage planning and communication between the two teams (we will talk more about this in the Impact section).
Define clear rules for qualifying the creation of an additional organization. This approach will not only help identify what’s important to your enterprise, it will also make it easy for anyone in your enterprise to understand the boundaries and purpose of each organization.
Possible rules could be:
Moving beyond high level overviews and guidelines, let’s discuss how you can leverage organization-related features to impact the level of control and innersourcing.
Each organization has its own pool of users and/or owners. Aside from **internal repositories and internal packages, **only users from within the organization are able to collaborate on non-public resources in an organization.
We recommend making strategic use of internal repositories and packages whenever possible.
Internal repositories and packages at GitHub are visible to every full member of the enterprise by default (outside collaborators are not full members, only collaborators) even if they do not belong to the organization the repository or package belongs to. They can interact with the repository in a read-only manner by opening and commenting on issues and, depending on enterprise policy, fork those repositories into their own organization’s or private space, allowing for open source like contributions through pull-requests. In this way, internal repositories help automate an innersource, “open by default” approach without having to apply piecemeal policies for every repository in every organization. This can also alleviate some of the administrative overhead of managing repository visibility and discoverability across multiple organizations. To take it a step further, you can make “internal” the standard, default repository visibility for new repositories in your organizations, though you may still want to allow for other visibilities where the need arises.
A few helpful tips and insights when it comes to permissions and visibility:
Having the ability to view and interact with resources is one thing. How easy it is to locate them is another matter altogether. The discoverability of resources is a critical aspect of innersourcing.
There are several ways to search and discover resources in GitHub, the most common being:
Increasing the number of organizations can make it easier to find resources if you are aware of their location, but it can become considerably more difficult if you are not. As the number of organizations grows, the “where to look” aspect may become more and more ambiguous. Establishing efficient innersourcing practices is often dependent on the ability to easily locate resources across team boundaries.
Consider the case of user-tagging as an example. If your developers can easily @-tag a team from anywhere or search for its existence within an organization, they are much more likely to reach out to the team. In contrast, if your developers had to leave their current context, search for the team, and open an issue in one of their repositories to contact them, it would be more cumbersome.
GitHub offers a variety of integration options through GitHub Apps, Webhooks, and APIs, which can be leveraged to enforce good development practices, such as branch protection rule sets, workflows, and more. It is important to note that most of these integrations are scoped to organizations, so they cannot be installed on enterprise level.
Thus, installing and configuring GitHub Apps and Webhooks for each organization individually can increase the administrative burden. App installations using the GitHub REST API are limited to the repository level. Many GitHub Apps available in the marketplace only allow connection to a single external system due to tool limitations (for example, the Azure Boards integration.) You may run into limitations with how to configure your integrations with a single-tenant tool across a multi-organization GitHub setup.
As the number of organizations in your enterprise increases, the complexity of implementing enterprise-wide automation using the GitHub API also grows; this is due to authorization scope. For example, listing repositories can only be done at the organization level. Therefore, if you want to list all repositories in your enterprise, you must first list all organizations and then loop through each one, which requires a broader range of permissions.
More organizations can provide greater flexibility, as it allows for individualized integrations and fine-tuned permissions. Though, this should be balanced with calculating the increased administrative overhead for the enterprise-wide automation.
There are several other features than can be impacted by your organization structure to take into consideration:
https://github.com/octoinc-org) under which all other resources are grouped (for example, https://github.com/octoinc-org/my-repository). There is no such grouping for an enterprise, meaning the enterprise URL (for example, https://github.com/enterprises/octoinc-enterprise) is mostly used for administrative purposes.That was a lot to digest, so let’s try to sum things up.
In general, it’s recommended to minimize the number of organizations in your enterprise. Each additional organization can increase administrative overhead and potentially make collaboration more challenging. To counter that, more organizations provide greater flexibility on an individual level and may be necessary to protect resources in order to comply with regulatory or other restrictions. Furthermore, the key is to find a balance between the two using DevSecOps and Innersourcing principles.
DevSecOps and Innersourcing are proven methods for improving developer productivity by fostering collaboration. However, in an enterprise, restrictions and limitations exist that make it a challenge to foster this culture. In GitHub, organizations are the biggest lever to achieving both, improving collaboration and culture and staying compliant. The organization structure has many impacts on many features of GitHub, how they can be used (or how easy it is to use them), and thus how easy it is for developers to work together.
A good starting point is to ask yourself the following questions:
We also highly recommend reading “The Book on GitHub Enterprise Cloud Adoption”—specifically, the chapter about organization structure as it will dive deeper into these archetypes.
For example, the ‘Red-Green’ Architecture above is a very elegant way of limiting the impact of restrictions to specific organizations, while having a main-innersourcing-organization where collaboration can thrive.
Read more about best practices for structuring organizations in your enterprise in our documentation.