Best practices for organizations and teams using GitHub Enterprise Cloud

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.

DevSecOps, Innersource, and GitHub

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.

Enterprise challenges

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.

What is a GitHub organization?

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.

• From the perspective of your end users, organizations are the highest level of abstraction of your enterprise, defining boundaries of what they can see and do in your enterprise. Users can be grouped in teams within organizations, but organizations are the only way to strictly group various resources such as apps, teams and repositories within an enterprise at GitHub.
• From the perspective of an enterprise administrator, organizations are a grouping mechanism to set up a group of policies, controls and reporting mechanisms among a set of repositories and teams.

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.

What is a team?

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.)

General guidelines

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.

1. Make maximizing collaboration and visibility your main goal

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.

2. Less organizations lead to less siloing and overhead

“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.

3. It’s easier to scale out than to scale in

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.

4. Organize based on product ownership and shared responsibilities

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).

5. Establish clear rules for organization creation

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:

• An organization can only be created for strictly separated legal entities or subsidiaries where developers are not allowed to discover each other or each other’s work
• Organizations are used as a grouping of related projects and services of decoupled business sections (for example, in a bank this could be retail, wholesale and wealth management) or fundamental, reusable core services (landing zone, corporate identity UI framework, internal billing system)
• New organizations can only be created for specific use-cases that do not directly drive business value and will never overlap in function. For example, an organization for a recruiting-hackathon or an organization to fork internal open source repositories so they can be vetted and scanned by the security team

Feature Impact

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.

Permissions and visibility

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:

• Standardize team structure. Users can only tag teams and other users from within the same organization. Therefore, use consistent namings and duplication where it makes sense to enable quick communications and collaboration across team-boundaries and multiple organizations
• Be mindful of non-admin user visibility. Any member of the organization will be able to see all members of an organization. If you have to shield users from each other, multiple organizations is the only way. Additionally, enterprise members will always be able to see the names and existence of all organizations within the enterprise
• Be mindful of administrator permissions. Resources can be hidden within an organization, but access to an organization can be granted both by enterprise and organization administrators. If you truly need to shield repositories, projects, or packages from each other, having separate organizations is the safer way as only enterprise owners can control organization creation.
• Use automation. You will have to take care of permissions-settings for every organization individually. When it comes to maintenance, this can increase depending on the number of organizations.

Search and discoverability

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:

• From the organization view, search on any type of resource (repositories, teams, packages, users, projects) by its name.
• Use the newly improved general search. The search can be scoped to a single organization, using org:<org-name>, but not to an enterprise.
• Customize your organization profile page with pinned repositories and organization profile READMEs.

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.

Apps, Webhooks and APIs

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.

Impact on other features

There are several other features than can be impacted by your organization structure to take into consideration:

• Teams roll up to the organization level only, not higher.
• Secrets and action variables can be configured at the organization level, but not higher.
• Every organization has its own, unique URL (for example, 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.
• An organization will inherit policies and settings enforced on an enterprise. Enterprise-level policies do not allow exceptions; they apply globally across the enterprise. Whatever is not enforced as an enterprise-level policy can be individually set per organization.

Long story short

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.

Where to go from here?

A good starting point is to ask yourself the following questions:

• What is your target culture? How do you envision the future of development within your enterprise?
• What limitations exist in your enterprise? Which ones can you get around? Which ones are unavoidable?
• Which GitHub features and their impacts are most important to you in your enterprise?
• Who will be the people most impacted by those decisions? Who do you need to convince?

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.

To learn more

Read more about best practices for structuring organizations in your enterprise in our documentation.

Written by

David Losert

@davelosert

Elizabeth Barrord

@elizabethbarrord