Having an organization with members grouped into various teams can be useful simply for understanding who is doing what, but GitHub provides you with tools that make your workflow even more effective when you group organization members into teams.
1. Creating parent/child teams
You can add a team as a parent team to a new team that you’re creating (see the section “Creating teams within your organization,” earlier in this chapter). Essentially, teams can have hierarchies. The permissions of the parent teams are passed down to all child teams, but not vice versa. Hierarchies can become extremely useful when you want to ensure that everyone within an organization has access to exactly what they need and no more, no less.
As an example, you may have a team named Employees at the top of your hierarchy. As part of that team, you may have three other teams: Human Resources, Marketing, and Engineering. Under the Human Resources team, you may have some private project boards or private repositories that only the Human Resources team members should be able to see (such as employee personal information).
Under the Marketing team, you may have customer data that shouldn’t be shared publicly within the organization (such as billing account information). By assigning all the employees to respective child teams within the organization, you can ensure that everyone has access to the employee handbook, while only the folks in Human Resources have access to Social Security numbers.
2. Discussing teams
GitHub offers the feature of team discussions when you have an organization with teams. Figure 11-9 shows this team discussion home page, which you can find at the URL https://github.com/orgs/ORGNAME/teams/TEAMNAME where ORGNAME and TEAMNAME are replaced with the actual names of the organization and team, respectively.
From the team discussion home page, you find
» Organization breadcrumbs: On the top left, the hierarchy of this team, all the way up to the organization in a clickable breadcrumb-like fashion for easy navigation.
» Team-specific actions: On the top right, similar menu items that are found on repositories and the organization itself, but all will be specific to this team.
» Team discussion: In the center right, a place to add new posts to the team discussion page. Below this area, you can find previous posts, and you can even pin specific posts to stay at the top (useful for important announcements or onboarding information).
» Team alias: The team alias appears below the team avatar and name on the left hand column. You can use this alias to notify everyone in the team about something that may be of interest to them, as seen in the team post.
» Team members: A list of all team members, a count of how many also belong to child teams, and a quick button for adding additional members to the team.
» Personal notification settings: On the left hand column, a place to quickly change your notification settings for this team.
» Child teams: A list of all child teams to this team that are linked for quick navigation, located on the bottom of the left column.
3. Assigning CODEOWNERS
A really neat feature that GitHub has that is enhanced with the use of teams is the CODEOWNERS feature. CODEOWNERS is a way to specify certain people who may have the most experience and knowledge on a piece of code. They’re the people that, when you’re looking for someone to review your code, you most likely want them to take a look. They probably have the most history with the code or are the most expert in that domain. By creating teams within your organization, you can assign multiple people to be CODEOWNERS of certain code, without having to assign each person or keep the list up to date.
To get CODEOWNERS working on one of your repositories, first make sure that you have a team setup that includes members of the organization that should be held responsible for ensuring all code that gets added to that repository is correct. In our example, I have a team called GitHub For Dummies which includes us two authors. On that team page, make sure that you’ve linked the repository that you want this team to be CODEOWNERS of and make sure that this team has at least Write access to that repository. Figure 11-10 shows that our team has two repositories that we have Write access to: the public one that you can access as a part of this book, and a private one that we’re using to track the progress of writing this book. We’re going to use CODEOWNERS for the public repository.
If you give the team only Read access to the repository, then they can’t approve or merge a pull request because that is technically writing to the repository. CODEOWNERs (whether individuals or teams) must have either Write or Admin access to be effective.
In the repository where you want the CODEOWNERS to be automatically added as a reviewer for all pull requests, add a file on the master branch .github/ CODEOWNERS with the following code:
# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @thewecanzone/github-for-dummies will be requested for
# review when someone opens a pull request.
* @thewecanzone/github-for-dummies
Make sure under the Settings for that repository, you’ve added a branch protection to ensure that every time someone tries to make changes to the master branch using a pull request, they have to get their code reviewed and approved by at least one person and that each pull request requires a CODEOWNER to review and approve it. You can set up these requirements in the Branches area of the Settings for the repository, as shown in Figure 11-11.
Now, when you try to add code by opening a pull request, the team @thewecanzone/ github-for-dummies will be automatically added to every single pull request, as you can see in Figure 11-12.
TIP: You can also add specific people or more teams to the CODEOWNERS file by appending them to the same line. And you can even specify what type of files you want to assign to which Code Owners. For a detailed explanation on all of the nuances, you can visit https://help.github.com/articles/about-code-owners.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.