Chapter 22: Organizing Your Teams

In this chapter, you’ll learn about the best practices for structuring your repositories and teams into organizations and enterprises to foster collaboration and facilitate administration.

In this chapter, we will cover the following topics:

  • GitHub scopes and namespaces
  • Structuring GitHub teams
  • Role-based access
  • Custom roles
  • Outside collaborators

GitHub scopes and namespaces

The main entities in GitHub are repositories. A repository can be created for a user or an organization. The URL of the repository will be in the following format:

https://github.com/<username>/<repository>
https://github.com/<organization>/<repository>

For GitHub Enterprise Server, you must replace https://github.com with the URL of your server. A user and organization name on a platform must be unique since they provide a namespace. The name of a repository must be unique in that namespace.

GitHub enterprises

In GitHub, an enterprise is a container for multiple organizations. Enterprises are not namespaces – the organization names must still be unique. Enterprises have a URL slug that is used to refer to the enterprise. The URL to your enterprise will look like this:

https://github.com/enterprises/<enterprise-slug>

If you own an organization that is paid by invoice, then you can upgrade to an enterprise under Settings | Billing and plans. Otherwise, you must contact GitHub sales.

A GitHub enterprise has three roles:

  • Owner: Has full administrative rights to the enterprise but not to organizations
  • Members: Members or outside collaborators with access to at least one organization
  • Billing Managers: Can only view and manage billing information

There are some settings you can configure at the enterprise level for all organizations, such as SAML authentication, SSH Certificate Authorities, or an IP allow list. There are also some enterprise-level webhooks and you can access the audit log for the entire enterprise. Audit log streaming to cloud storage, Splunk, or Azure Event Hubs is only available at the enterprise level, but most of the settings are around billing and licensing.

You can also set policies for many of the settings that can be configured at the organization level. If a policy has been set, the owner of the organization cannot change the settings. If a policy hasn’t been defined, the setting can be configured by the owners of the organizations.

GitHub organizations

The main way to manage your repositories and teams is by using organizations. They can also exist without an enterprise, and you can move them between different enterprises. Organizations are not meant to be given out as a self-service for your teams to organize themselves. Some companies have more than 2,000 organizations – and this is a big problem, especially for managing integrations. GitHub Apps, for example, can only be configured at the organization level – not at the enterprise level. If you want to configure integration with your Jira instance, then you must do this for all organizations. You cannot configure this at the enterprise level.

One organization should be enough for most customers. If your company has different legal entities that must be separate, then this might be a reason to have multiple organizations. Another reason would be if you want to separate open and inner source. However, you should not have one organization for all departments or divisions. It is better to use teams for that.

An organization has the following roles:

  • Owner: Has full access to teams, settings, and repositories
  • Members: Can see members and non-secret teams, as well as create repositories
  • Outside Collaborators: These are not members of the organization but they have access to one or more repositories

Organizations have projects, packages, teams, and repositories. You can configure many settings for repositories. If you don’t configure these settings at the organization level, these settings can be set at the repository level.

The main way to structure your organization is by using teams. We’ll look at these in the next section.

Structuring GitHub teams

Teams are not just the more convenient way to grant permissions to repositories that allow faster on- and off-boarding. They can also be used to share knowledge and notify certain groups of changes.

Teams have discussions, and you can see their repositories and projects. Teams can have one of the following two visibilities:

  • Visible: A visible team can be seen and mentioned by every member of this organization
  • Secret: A secret team can only be seen by its members and may not be nested

A team exists in the namespace of an organization. This means that the name of the team must be unique inside the organization. You can mention a team or add it as a code owner using the following syntax:

@<organization>/<team-name>

You can use teams to reflect your company or group’s structure with cascading access permissions and mentions by nesting them. You can do this by specifying a parent team when creating a new team. This makes the new team a child team. Child teams can also be parent teams – this way, you can create a deep hierarchy. Teams inherit permissions and notifications from their parent teams, but not the other way around.

By nesting teams, you can create the structure of your company. You could create a team for all employees, each division, each department, and each product team (vertical teams). You can also use teams for horizontal teams – interest groups such as communities of practices (see Figure 22.1):

Figure 22.1 – Structuring your organizations using teams

Figure 22.1 – Structuring your organizations using teams

This allows you to share knowledge and ownership across your value stream teams. You can also nest horizontal teams if this fits your community structure.

Nested teams can be expanded in the Teams tab of an organization (see Figure 22.2):

Figure 22.2 – Nested teams in the Teams tab of an organization

Figure 22.2 – Nested teams in the Teams tab of an organization

Teams have pages for discussions. Organization members can create and participate in discussions with the team, but the team can also have private discussions that are not visible to the rest of the organization (see Figure 22.3):

Figure 22.3 – Team pages with discussion

Figure 22.3 – Team pages with discussion

Teams can be mentioned and assigned as reviewers and code owners. It is a very powerful tool for structuring your organization simplistically. But try to keep it simple and use names that people can easily understand. You don’t want to build a bureaucratic monster! Keep it simple.

Role-based access

At the repository level, you can grant role-based access to teams or individual people. You can use one of the following default roles:

  • Read: Read and clone repositories. Open and comment on issues and pull requests.
  • Triage: Read permissions, plus manage issues and pull requests.
  • Write: Triage permissions, plus read, clone, and push to repositories.
  • Maintain: Write permissions, plus manage issues, pull requests, and configure some repository settings.
  • Admin: Full access to repositories, including sensitive and destructive actions.

Note that the read role can do more than just read! It can open and comment on issues and pull requests. Triage and maintain are typical roles in open source projects. They are not so commonly used in enterprise scenarios.

You can set a base permission for an organization to read, write, or admin. This will grant all members the corresponding permission to all repositories. Outside collaborators do not inherit the base permission (see https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/setting-base-permissions-for-an-organization for more information).

Custom roles

You can define custom roles in the organization settings under Repository roles (/settings/roles). Click Create a role and specify a name and description for the new role. Then, select a default role to inherit the permissions from and add permissions to it (see Figure 22.4):

Figure 22.4 – Creating custom roles in GitHub

Figure 22.4 – Creating custom roles in GitHub

The permissions are categorized. So, if you type security in the search box, the list will show you all the available permission related to security.

Permissions are available in the following categories:

  • Discussions
  • Issue
  • Pull request
  • Repository
  • Security

Note that not everything is configurable. For example, there are no specific permissions for GitHub Packages at the time of writing.

If a person is given different levels of access, the higher permissions always override the lower ones. If a person has been given multiple roles, a warning will appear on GitHub next to the person with Mixed roles.

And again: try not to go too crazy with custom roles. Keep it as simple as possible.

Outside collaborators

An outside collaborator is a person who is not a member of your organization but has access to one or more of your organization’s repositories.

Note

Adding an outside collaborator to a private repository will consume one of your paid licenses!

Outside collaborators are not members of your organization. They don’t see internal repositories and they do not inherit base permissions.

You can’t invite outside collaborators at the organization level – you can only invite members to your organization and then convert them into outside collaborators, (see Figure 22.5):

Figure 22.5 – Converting members into outside collaborators

Figure 22.5 – Converting members into outside collaborators

As a repository administrator, if you Add people under Settings | Collaborators and teams, if they already belong to the organization, they will be automatically added as members. If not, they will be added as outside collaborators.

Outside collaborators are a great way to easily collaborate with partners and customers without requiring them to be part of your organization. But keep in mind that this does not work if you use Enterprise Managed Users. And if you have SAML Single Sign On enabled, outside collaborators will bypass that. That’s why organization owners can prevent repository administrators from inviting outside collaborators to repositories in the settings of the organization.

Summary

In this chapter, you learned about the best practices for structuring organizations, repositories, and teams in your enterprise. We talked about nesting teams, using teams for interest groups, role-based access, and outside collaborators.

In the last chapter, we’ll put all the pieces of this book together and guide you through the process of using GitHub to transform your enterprise and use it to accelerate DevOps in your organization.

Further reading

Please refer to the following links and further GitHub documentation to learn more about the topics that were covered in this chapter:

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset