If you think back to the first guide of this learning pathway, you’ll remember that we laid out GitHub Enterprise Cloud’s (GHEC) basic hierarchy of structural components. At the top sits the enterprise account, which can contain one or more organizations. Each organization can then contain any number of teams to which its members can be assigned. Teams and member roles sit at the very bottom of this structural hierarchy and provide the most fine-grained controls regarding individual member capabilities and access.
It’s through these components that you'll be able to most closely mirror your internal structure in GHEC, so let’s take a look at how they work and the options available to you.
For HelloFresh and Philips, teams offered the perfect way to automate permissions and empower their developers.
In this guide, you will learn:
How to use teams to grant permissions to groups of users to facilitate collaboration, communication, and simplify access management
What default roles are available at the organization level and the permissions they grant
What default roles are available at the repository level, the permissions they grant, and how to create custom repository roles
Inviting and assigning users to organizations
Users need to be given access to organizations in order to gain access to content. For enterprises using Enterprise Managed Users (EMUs), you will assign users to organizations. For enterprises not using EMUs, you will invite users to organizations, and they will need to accept the invitation.
The best way to manage user membership in your organizations is to add users to teams, because it allows you to use automation like group SCIM (EMU) or organization SCIM (non-EMU) to manage organization membership. Managing organizations through automation means you don’t have to remember to remove users manually to ensure their access and license are removed if and when they leave an organization. You’ll just need to make sure they are removed from all of their assignments, which will also then remove them from the organization and revoke their license (provided this is the last organization they were a member of in your enterprise).
If you don’t manage a user’s access through SCIM, it is also possible for an organization owner to directly invite a user to a non-EMU organization. This can be done on the organization’s People page. When a user is invited manually, their invitation will expire if the user does not accept it in seven days, but it can be re-sent again if it expires. Invitations can also be canceled if needed. If you invite users manually in this way, you will need to be sure to either manually remove users when they leave, or build in your own automation to remove users, since manual invitation does not have a built-in deprovisioning process.
Use teams to grant permissions
Permissions can be granted to teams and individuals. When possible, enterprises should grant permissions using teams, whose membership can be synced with identity provider (IdP) groups. Creation of these permissions can be automated using webhooks and the GitHub API.
Our developers don’t have to wait for the IT team to manually provide access anymore. We sync our Azure users and groups with GitHub, and use Terraform to provide access to the repositories. If users need access to a repository, for example, they raise a pull request and the rest is taken care of by our infrastructure-as-code automation.
Every user account in an enterprise is a member of the enterprise. You can also assign administrative roles to members of your enterprise. Each administrator role maps to business functions and provides permissions to do specific tasks within the enterprise.
There are two administrative roles available in enterprises:
Enterprise owners, who can access and manage all settings across the enterprise and see all of the members and outside collaborators for every organization owned by the enterprise.
Billing managers, who can access and manage only the enterprise's billing settings.
In an enterprise using EMUs, all new enterprise members, including administrative roles, must be provisioned through your IdP. All changes and assignments must be done via the IdP, and even enterprise owners and organization owners cannot add new members or owners to the enterprise using GitHub.
For standard enterprises, administrative roles can be assigned to existing enterprise members, or new members can be invited by email or GitHub account username. Users, including administrators, will need to sign in with a GitHub.com account, or create one if they don’t have one, to accept their invitation to become an enterprise owner or billing manager.
The organization member is the default, non-administrative role for people in an organization. They have a number of permissions by default, including the ability to create repositories and project boards, although these can be changed by enterprise or organization policy.
Organization owners have complete administrative access to your organization, including full access and control over all repositories in the organization. This role should be limited to only the number of users required to support your business needs, since organization owners possess permissions for potentially destructive or sensitive actions. However, there should always be more than one organization owner in each organization for contingency purposes, in case one is unavailable, leaves, or loses access. Existing organization owners can promote other members who have been assigned to your organization or accepted invitations to your organization to the organization owner role.
Since we operate in a single GitHub organization to promote innersource, we let teams manage their own permissions for their repositories and we don’t enforce anything at the organization level. Of course, we also strongly advise them to follow the principle of least privilege by providing only the minimum level of access that is necessary. We use IssueOps to grant just-in-time access to GitHub organization administrators, that way they can’t accidentally make any changes without realizing they’re doing so.
An outside collaborator is someone who has access to one or more organization repositories but is not explicitly a member of the organization, such as a consultant or temporary employee. Outside collaborators are invited directly per repository using their GitHub account or email address. You can choose the level of access to grant for each outside collaborator for each repository you add them to. Administrators can restrict the ability to invite collaborators by enterprise or organization policy.
Enterprises using EMUs cannot add outside collaborators because all users must be provisioned from the connected IdP.
Security manager is an organization-level role that organization owners can assign to any team in an organization. When applied, it gives every member of the team permissions to manage security alerts and settings across your organization, as well as read permissions for all repositories in the organization.
If your organization has a security team, you can use the security manager role to give members of the team the least access they need to the organization. It also can be useful for auditors and others that might need this read-only access with visibility to security information.
Billing managers are users who can view and manage the billing information and settings for a specific organization. This is a useful option for multi-organization enterprises where you might not want to grant full enterprise billing manager rights to some users, but may want to give them access at the level of certain organizations.
GitHub App manager
By default, only organization owners can manage the settings of GitHub App registrations owned by an organization. To allow additional users to manage GitHub App registrations owned by an organization, an owner can grant them GitHub App manager permissions.
When you designate a user as a GitHub App manager, you can grant them access to manage the settings of some, or all, GitHub App registrations, but they cannot install and uninstall GitHub Apps on an organization.
People with the team maintainer role can manage team membership and configure a few team settings, like team name and avatar. Organization owners can assign the team maintainer role to users that are already members of that team.
Teams that use IdP groups to automate membership do not and cannot have maintainers by design. This is because there is a very limited scope of work for a maintainer to do when they cannot manually update user membership in the team. Organization owners can change settings for IdP group-managed teams when required.
Repository roles and permissions
GitHub provides three different types of default repository permissions:
Read allows all organization members to see the repository, clone it, and participate in issues. If forking is allowed in your enterprise, users can fork the repository, too.
Write allows all organization members the ability to push code to the repository. It does not necessarily let members push to the default branch or approve their own changes. Properly configured mergeability controls control how members can modify the code.
Admin allows all organization members to administer the repository. This should not be used as a default, given its overly permissive nature.
GitHub also provides a set of repository roles, including Read, Triage, Write, Maintain, and Admin, which can be explicitly granted to individuals or teams. Triage and Maintain roles are typically more useful to open source communities than enterprises. If you find that you need additional roles, you may want to explore custom repository roles, which we discuss below.
Auditing and managing repository access
For each repository that you administer on GitHub, you can see an overview of the repository visibility, base visibility, and direct access, as well as a detailed view of every team or person with access to the repository. This view allows you to search and filter by teams and individual users, invite new teams or people, change each team or person's role for the repository, or remove access to the repository.
This overview can help you audit access to your repository, onboard or off-board contractors or employees, and effectively respond to security incidents.
If a person has been given conflicting access or permissions to a repository, you'll see a warning on the repository access page. Conflicting access can occur when direct assignments or custom roles grant specific access to a user that they otherwise would not receive through their usual team or inherited roles and permissions. When a user has conflicting access, a warning icon appears on the repository access screen with "Mixed roles" next to the person’s user listing. To see the source of the conflicting access, hover over the warning icon or click the “Mixed roles” indicator. You do not necessarily need to “fix” conflicting access. This information is there for your awareness so that the conflicting access does not cause confusion about why a user has certain permissions.
When different levels of access are given through different routes, such as team membership and the base permissions for an organization, the highest access overrides for each specific permission. For example, if an organization owner gives an organization member a role that uses the "Read" inherited role, and then an organization owner sets the organization's base permission to "Write", this custom role will have write access, along with any additional permissions included in the custom role. These different levels of access may cause the conflicting access flag to display in the repository access overview as described previously.
Custom repository roles
You can have more granular control over the permissions you grant at the repository level by creating up to five custom repository roles per organization. When you create a custom repository role, you start by choosing an inherited role from the default set of pre-defined options: Read, Triage, Write, Maintain, and Admin. The inherited role determines the initial set of permissions included in the custom role. Then, you can further customize the role by choosing additional permissions to give the role.
After you create a custom role, anyone with admin access to a repository can assign the role to an individual or team.
Integrating GHEC with an enterprise’s various systems requires a thoughtful, layered approach. Up next, we’ll explore the various ways to programmatically access the GitHub API so you can integrate your existing systems without running into hurdles.