Configure your GitHub Enterprise Cloud enterprise settings and policies
In our last two guides, we established your enterprise account and chose a user model. Now, it’s time to configure settings and policies that apply to all development work. Configurations and policies not applied at the enterprise level are managed in each organization. This lets you manage your desired balance between centralized and distributed administration. Most policies, configuration options, and settings you see at the enterprise level have an equivalent at the organization level, though both have a handful of unique configuration items and settings as well.
It’s a best practice to review your policies and configurations with all stakeholders, including members from development, security, operations, and any other affiliated teams. You want to optimize for both the collaboration and flexibility your end users need to get their work done, as well as the compliance and security requirements you need to protect your company.
Enterprise policies are broken down by topic. We’ll highlight some of the most important items for each topic in this guide, skipping over less commonly-configured items. Please refer to the enterprise policy documentation for comprehensive details on these settings.
As you explore your GitHub Enterprise Cloud (GHEC) configuration, you’ll notice settings for GitHub Copilot, GitHub Actions, GitHub Codespaces, and GitHub Projects. We’ll discuss these in the next guide when we explore billing, as some are licensed separately from GHEC, so the settings can have other billing implications.
But first, we’ll hear from Fidelity on how they standardized repository creation to balance collaboration with security, and they verified their configuration decisions with stakeholders across the company.
In this guide, you will learn:
The various policies available for configuring your enterprise or organization, including base permissions, the ability to create and fork repositories, and more; and guidance for setting them where applicable
Enterprise settings and features, including compliance reports and support
A note about “No policy”
Enterprise policies always offer a “No policy” option, which allows each organization to set their own policy for that particular configuration item. It does not mean you are actively not setting a policy, but rather that you’re not choosing to set the same policy across the board at the enterprise level. “No policy” is useful for enterprises that have multiple organizations, each with different configuration needs.
Repository policies
Repository policies relate to the creation and visibility of your repositories, and encompass some of the most sensitive settings in your enterprise. Be sure to review these items carefully, whether at the enterprise level or at each organization level.
Repository access base permissions
Base permissions are the inherited, default repository access permissions granted to all full members (not outside collaborators) in your enterprise, and can be a useful shortcut to an innersource culture. They set a baseline level of access to all users and can be used to encourage visibility and collaboration without needing to micromanage team and individual access assignments for every newly created repository. Of course, you’ll also want to consider whether it’s appropriate for all of your organizations to have the same level of default openness, or if you should instead set separate policies per-organization instead.
Base permission options include:
No permission: No default base permissions are granted on repositories for organization members. You will need to manage the visibility of private repositories through direct assignment of teams and users instead of through a base permission.
Read: Organization members will receive read access to all organization repositories by default. This is effectively an innersource setting. It allows all organization members to view, clone, or create pull requests, but not merge them.
Write, Admin: Organization members will receive write or admin access to all organization repositories. These are highly permissive defaults and not recommended for enterprises.
Repository creation policy
Who will you allow to create repositories in your organizations? This is another critical policy to consider, and each option comes with its own set of considerations:
Members can create repositories: If set at the enterprise level, users are able to create repositories in organizations in the enterprise using the allowed visibility types for your enterprise. EMU enterprises will not be able to select public repositories. Organization owners will always be able to create all possible visibilities of repositories, regardless of what you select here.
Disabled: This will prevent your end users from creating repositories in the enterprise, although organization owners will still be able to create repositories. Companies use this policy setting because they plan to use an automated process to create repositories from standard configurations.
Block the creation of user namespace repositories: This option is only available to EMU enterprises. EMU user namespace repositories are repositories owned by a specific EMU user account, not by an organization. Some enterprises choose to leverage these personal spaces as a sandbox for developers. Others choose to block them to keep development contained within just the organization space, where enterprise and organization policies can be consistently applied.
Keep in mind that repository creators are automatically granted administrative permissions on the repositories they create.
We set enterprise-wide security policies to ensure every repository is properly secured, and then use organization-level policies to provide more fine-grained differentiation around access and corporate code. We built a self-service portal to drive repository creation, that way we can enforce that these standards are universally applied and compliant. This approach allows us to balance our need for collaboration with that of security.
Repository forking policy (and a note on forking)
A fork is a new repository that shares code and visibility settings with the original upstream repository. Forks are often used to iterate on ideas or changes before they are proposed back to the upstream repository, such as in open source projects or when a user does not have write access to the upstream repository. They were originally designed by the community for use in open source and other low-trust scenarios where managing write permissions would be difficult. For this reason, forks aren’t necessarily the best fit for the enterprise context, where you can verify user identity and easily manage permissions using your identity provider (IdP), teams, and other automation. Nonetheless, some teams still use forks to support specific types of workflows or tools. A repository forking policy helps control where these forks can be created so you can keep them organized and secure.
Note for EMU customers: Forking policy settings are overridden by the repository creation policy we just discussed if it is set to block the creation of user namespace repositories. In this case, members will not be allowed to fork a repository in their user accounts either, regardless of your repository forking policy.
The options for allowed repository forking locations are:
Organizations within this enterprise: Members can fork a repository to any organization they have access to within the enterprise.
Within the same organization: Members can fork a repository only within the same organization that owns the parent repository. This option maintains full visibility of forks, instead of having them spread out over many different locations.
User accounts and within the same organization: Members can fork a repository into the same organization as its parent repository, as well as into the user namespace, but this presents differences by user models. For EMU enterprises, this is the enterprise-managed user account namespace, which is inside the enterprise and its control. For non-EMU enterprises, this is the individual user’s account namespace, which is outside the enterprise and its control.
User accounts and organizations within this enterprise: This setting has the same distinction between EMU and non-EMU enterprises for user account forking. EMU enterprises allow forking into the enterprise-managed user account namespace and non-EMU enterprises allow forking into the individual user’s account namespace. Additionally, members can fork a repository into any organization inside this enterprise, not just the owning organization for the parent repo.
User accounts: For EMU enterprises, members can fork a repository only into the enterprise-managed user account namespace. For non-EMU enterprises, members can fork a repository only into the individual user’s account namespace . In both cases, members cannot fork into an organization. This keeps their organization spaces clean of forks but still allows for them.
Everywhere: Members can fork repositories anywhere, including user accounts, namespaces, and any organization, even outside of the enterprise for non-EMU enterprises.
Outside collaborator policy
An outside collaborator is someone who has access to one or more organization repositories through direct invitation, but is not explicitly a member of the organization, such as a consultant or temporary employee. We’ll learn more about them in the guide on teams, roles, and users.
This policy allows you to select which level of administrator is able to invite outside collaborators to your repositories: enterprise owners, organization owners, or repository administrators.
EMU enterprises will not see this policy, as all users must be provisioned from the connected IdP and cannot be created by owners or administrators.
While requiring enterprise or organization owners to invite outside collaborators centralizes the administration and control over collaborator access, it can also potentially cause bottlenecks. Allowing individual repository administrators to manage these invitations, on the other hand, grants the invitation permission to more users but could mean looser control over who is given collaborator access.
Default branch name policy
This policy sets the default branch name for all repositories across all of your organizations. You might want to change the default name due to different workflows or because your integrations require a specific default branch name.
Unlike some other policies, this can be overridden at the repository level unless you select Enforce across this enterprise.
Repository visibility change, deletion, and transfer, and issue deletion policies
These policies all similarly govern whether you want to allow users with repository administrator permissions to perform these potentially destructive or disruptive actions, or if you want to limit these actions to organization owners, who will always have these administrative capabilities for all repositories. Enable the given option to allow repository administrators to perform each type of activity, or disable it to keep the activity restricted to organization owners.
During the initial GitHub enablement process, we created a separate, non-production GitHub organization to test our policies and configurations. Since our stakeholders are spread throughout the company, we invited a number of cross representative teams to the organization, where they were able to try out various automation processes and experiment with the platform as we’d configured it. They formed a stakeholder working group to collect feedback, which was then provided to the GitHub enablement team to help refine our policies and configurations before making it generally available.
GitHub Projects policies
Policies in this section govern use of GitHub Projects, GitHub’s developer-centric, built-in project management tool. Administrators can optionally disable use of projects in one or more organizations and govern project visibility changes. This can help with phased rollouts or if you want to allow use of other project management tools.
GitHub Connect configuration
GitHub Connect is a service that enables certain features by allowing limited data sharing between GitHub Enterprise Cloud and GitHub Enterprise Server, GitHub’s self-hosted enterprise offering. If you use GitHub Enterprise Server, you can enable and configure this functionality in this section.
Enterprise settings
Enterprise profile
In this section, you can set and change your enterprise account’s display name, description, website URL, and location. This information is shown to all enterprise members on the enterprise account profile page.
There is also a second tab on this page where you can set footers, which will display to users at the bottom of all pages in the logged-in enterprise context. These can be used to display required legal notifications or other data that must be perpetually visible to your GHEC users. As with any announcement text, be judicious in the use of these to display only necessary information to avoid extra visual noise.
Verified and approved domains
Verifying and approving domains control which domains are permitted to receive email notifications from their enterprise or organization. Domain verification requires access to the domain’s DNS record (i.e. domains your company owns) whereas domain approval can be used for domains that you don’t control but still want to allow-list, like those of vendors or contractors.
Verified (not approved) domains also will display a Verified badge on the profile of each organization that lists them as the URL in their organization profile information. This can add additional public-facing legitimacy for your organization pages.
Neither of these features are very useful for EMU enterprises and organizations given the standardized email addresses they use and the lack of public-facing presence, so most EMU enterprises don’t configure domain verification.
Announcement
In this section, you can create global announcement banners, which appear at the top of every enterprise page. To avoid alert fatigue and visual noise, we recommend that you only use this feature when absolutely necessary, and use the expiration date and dismissability options whenever possible.
Support
Your GHEC plan includes enterprise support by default. Enterprise support provides 24/7 ticket-based support staffed by GHEC support engineers. You may have also purchased or be entitled to premium support, which includes some additional benefits.
While any GitHub user can create support tickets, enterprise owners and billing managers automatically have a support entitlement, which enables them to create, view, and comment on support tickets associated with their enterprise account. Enterprise owners can also add these support entitlements to up to 20 regular users in organizations owned by their enterprise account.
Enterprise administrators and support-entitled users can open and manage their GitHub support tickets through the enterprise support portal.
Compliance reporting
Your security team will need to keep up to date with the latest compliance documentation as you review, onboard, and maintain GitHub as one of your vendor partners. We provide our latest SOC reports, third-party attestations, and self-reported business operations procedures as self-serve documents within the enterprise administration page for download.
Up next: Manage your billing, licensing, and consumption-based services
With many of our crucial policies and default permissions now configured, it’s time to take a look at those settings that relate to billing, licensing, and consumption services like GitHub Actions and Codespaces.