Use teams, roles, and users to manage repository access
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. Enterprises using Enterprise Managed Users (EMUs) will assign users to organizations, while enterprises not using EMUs will invite users to organizations, which will need to be accepted.
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).
We use a monorepo, so instead of using teams for access control, we use them as a communication mechanism. It’s really common for our developers to tag teams when they want feedback on something, or to alert them to an important fix, for example. At other companies, you’ll often see pull requests with just the submitter tagged, but we often tag our pull requests with multiple teams for visibility. Since this helps teams stay informed, and they’re incentivized to keep their teams up to date.
For non-SCIM access management, an organization owner can directly invite a user to a non-EMU organization. Manual invitations expire if they are not accepted within seven days, but can be re-sent or canceled, if needed. Manually-invited users will need to be manually removed when they leave, or you’ll need to build your own automation to remove them. 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 Active Directory 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.
Enterprise roles
Every user account in an enterprise is a member of the enterprise. At the enterprise-level, there are two administrative roles that can be assigned, each mapping to a business function and providing permissions to do specific tasks within the enterprise.
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.
Enterprises using EMUs must provision all new enterprise members, including administrative roles, and make all changes and assignments through their IdP. 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 on GitHub.com to existing enterprise members, while new members can be invited by email or GitHub account username. All users, including administrators, will need to sign in with a GitHub.com account to accept their administrative role invitation.
Organization roles
Member
The organization member is the default, non-administrative role in an organization. Members 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 owner
Organization owners have complete administrative access over an 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. Organization owners can promote other organization members 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.
Outside collaborator
An outside collaborator has access to one or more organization repositories but is not a member of the organizationConsultants or temporary employees often occupy this role. 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
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 manager
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.
Team maintainer
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. Custom repository roles start by inheriting permissions from a default role: Read, Triage, Write, Maintain, or Admin. You then customize the role by assigning additional permissions.
After you create a custom role, anyone with admin access to a repository can assign the role to an individual or team.
Up next: Programmatic access and integrations with GitHub Enterprise Cloud
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.