Many features and tools that GitHub.com users already love are also present in GitHub Enterprise. Organizations and teams are used in both GitHub.com and GitHub Enterprise to simplify management of users and content, as well as sharpen the GitHub workflow for both developers and businesses.
The best practices below were brought together to help GitHub Enterprise Site Admins manage users and set permissions to repositories efficiently, aiming for collaboration, great user experience and minimum maintenance effort.
Organizations and teams: quick tips
Users can create organizations
Should your users be allowed to create organizations? While the answer for this question will depend on your business needs, there are a few things you should keep in mind:
- As a Site Admin for your GitHub Enterprise appliance, more organizations means you will probably need to spend more time maintaining them.
- Although a Site Admin has access to many user-facing and non-user-facing areas of GitHub Enterprise, by default, a Site Admin is not granted owner permissions to new organizations. This means, for example, that if an organization owner is on vacation, or leaves the company, anything related to maintaining that organization may become difficult.
If you decide that only a small team of Site Admins should be able to create organizations, you can use the instructions on preventing users from creating organizations to make your selection.
Create as few organizations as possible
Whether you allow your users to create organizations or not, keeping as few organizations as possible in your GitHub Enterprise appliance helps avoid challenging situations.
- Having many organizations can make collaboration difficult, especially because @mentioning teams does not work across different organizations.
- Keeping as few organizations as possible helps keep a cohesive permission and administrative strategy. Consider creating fewer organizations in favor of many teams.
- Creating a separate organization for contractors or other third parties may facilitate access to specific repositories.
Team work makes the collaboration work
A multi-team structure allows for better collaboration and straightforward management:
- @mentioning a team, for example, sends notifications to all the members of the team.
- Relying on teams, rather than organizations, makes it easier to assign repository permissions instead of opening the repositories to your entire GitHub Enterprise instance.
- Team management can also be simplified with nested teams. Child teams inherit the parent’s access permissions, and members of child teams also receive notifications when the parent team is @mentioned. This simplifies communication with multiple groups of people.
- Team membership can also be managed by LDAP sync, in case you have selected LDAP as the authentication method for your appliance. There is more information about this in the Supporting organizations and _teams _section of this article.
Supporting organizations and teams
Site Admins are usually the first point of internal support for most things GitHub Enterprise. Keep the pro tips below handy, in case you want help choosing the configuration that best suits your workflow, or need to know how to quickly overcome a tricky circumstance.
Site admin != Organization owner
By default, the Site Admin role is not a “super user” role with access to all organizations. This means that a Site Admin needs to be granted permissions to the organization, as any other user account would.
What to do when, for example, the organization owner isn’t available and the Site Admin doesn’t have permissions to act on the owner’s behalf?
You can use the handy
ghe-org-admin-promote command-line utility to give organization owner privileges to users with Site Admin privileges or any single user in a single organization:
$ ghe-org-admin-promote -h Usage: ghe-org-admin-promote [options] Make users into organization admins Promote an individual user with the -u flag. If you don't specify a user, all site admins will be promoted. You can promote users to site admins via the site admin dashboard or the ghe-user-promote tool. Specify a single organization in which to promote the user with the -o flag. If you don't specify an organization, a site admin specified with -u will be granted admin privileges to all organizations. Note that the script will refuse to promote a non-site admin to be an admin of all organizations. OPTIONS: -h Show this message. -v Run in verbose mode. -y Bypass the confirmation prompt. -a Add all site admins as admins of every organization -u USERNAME Only add the specified user as an admin. -o ORGANIZATION Only add the user(s) as admin(s) of the specified organization.
Teams and authentication methods
While GitHub Enterprise offers different options for user authentication, LDAP and LDAP sync can automate team membership.
LDAP Sync allows Site Admins to synchronize GitHub Enterprise team members and team roles against your established LDAP groups. This lets you establish role-based access control for users from your LDAP server instead of manually within GitHub Enterprise.
If you are using LDAP, but still want to create and manage teams in GitHub Enterprise, you can. To create a non-mapped team, leave the LDAP group field blank when filling out the Create new team form:
Keep collaboration going by creating a multi-team structure rather than creating many organizations. This will help maintain a seamless GitHub workflow for users, as well as keep management effortless for Site Admins. GitHub Enterprise has features that guide Site Admins through the configuration and support of organizations and teams, such as LDAP Sync and the
As always, if you need extra help, contact us at GitHub Enterprise Support, or leave a comment here if you have questions about this article.