Understand the structural components of GitHub Enterprise Cloud

GitHub Enterprise Cloud (GHEC) provides a number of flexible configuration options, allowing each business to configure the platform to best meet their unique needs. While there is no single “best” way to implement GHEC, there are some common patterns and steps you should carefully consider.

Successful GHEC implementations begin with establishing a single enterprise account for all internal work. This will govern policy across your GitHub organizations, users, and teams, and be your single portal for managing billing.

Organization structures are constantly evolving, and your GitHub architecture should reflect your intention to promote a collaborative developer experience that respects the complex and dynamic nature of your business, while also meeting your security and compliance requirements. Let’s get started by exploring the core constructs of a GHEC account.

In this guide, you will learn:

GHEC’s structural components and how they relate to each other
How each component provides different levels of control
Initial considerations for using these components to configure your business and enforce requirements while promoting collaboration

Why does this matter to you?

In later guides in these learning pathways, you’ll be working with the different organizational constructs to build out your optimal setup and policy infrastructure to support your business needs. Understanding how these components interact is important to ensure you make the best decisions to fulfill your requirements.

Enterprise account

The enterprise account is the highest level construct within GHEC. The enterprise account is logically isolated, in that its resources are separated from other enterprises within GHEC by design. The enterprise account is purely an administrative container for billing, licensing, and other policies and configurations. Administrators use the enterprise account to manage how GitHub interfaces with internal business systems like your identity provider (IdP), licensing and billing, support tickets and entitlements, and log management. It also provides the ability to define and enforce policies governing the use of GitHub resources and capabilities that apply identically to all of the organizations within your enterprise account.

The enterprise account interface is only utilized regularly by enterprise administrator (owner) users. Standard end users do not typically have any need to interact with the enterprise account interface.

Organizations

Enterprises consist of one or more organizations to which users are added. Organizations are the “owners” of shared repositories, teams, discussions, and projects. They let administrators set more granular policies on repositories belonging to the organization, as well as user behavior within the organization. Policies not enforced at the enterprise level are distributed out to be defined at each individual organization. Organizations don’t typically map to business units. In general, we recommend that you have only one GitHub organization and use other features, like repositories and teams, to subdivide. However, there are legitimate business or legal reasons for employing multiple organizations, like providing a sandbox organization for training or testing, or spinning off a separate legal entity, and we’ll dive into some examples and strategies later.

Organizations also serve as a starting point to further drill down into billing, usage, and licensing data for reporting, which is aggregated at the enterprise account level. 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.

Organizations are typically the highest level construct an end user interacts with. For example, they might perform an organization-wide code search or log into an organization with SAML. Although there may be multiple organizations that your enterprise owners manage within an enterprise account, from an end user’s perspective the organizations function as completely separate containers.

Repositories

Repositories host your application source code and other files. They are the primary construct developers interface with on GitHub, including accessing application security metrics, CI/CD workflows, and other day-to-day activities.

Repositories roll up to the organization level. However, certain repository visibility options do allow for repositories to be visible as read-only to users that are outside of the organization, or even the enterprise. We’ll explore this further in our guide on repository visibility (or you can jump ahead to the documentation for repository visibility settings).

Teams

GitHub teams group users of common projects, specialized skills, or other infrastructural commonalities. Teams can provide role-based access to collections of repositories, allowing you to create permission management structures while keeping content discoverability and reuse as open as possible.

Teams used for permission management should be synced with an identity provider (IdP) group, which allows existing access processes and audit controls to manage access to code, onboarding, and offboarding.

Permissions aren’t the only use for teams, though. You can use GitHub teams to encourage collaboration among project teams and/or topic-based teams (not explicitly defined in your IdP). They can also be automatically assigned as reviewers to code.

In terms of hierarchy and configuration inheritance, teams roll up to the organization level. This means that in order to reuse the same team across many organizations within your enterprise account, you would need to recreate it in each organization.

Up next: Choose a GitHub Enterprise Cloud user access model

Now that you have an understanding of GHEC’s core structural components, our next step is to explore one of the first choices you’ll have to make as a new enterprise adopting GHEC: Should you use the standard or enterprise managed user (EMU) model?