GitHub Organizations Best Practices

Last Updated on March 5, 2024

As a popular platform for hosting and collaborating on code, GitHub is widely used by
organizations of all sizes. Managing a GitHub organization effectively is crucial for ensuring the
success of your projects and the security of your code. This blog post will discuss some best
practices for managing a GitHub organization.

What is a GitHub organization?

A GitHub organization is an account serving as a container to enable close collaboration for businesses or open-source projects. Organizations allow administrating of multiple teams and repositories. They come with special security and administrative features on repositories, such as sharing controlled access with members and collaborators. An unlimited number of people (GitHub users) can join an organization, and assume various roles within it.

What are the different GitHub roles?

What are the different GitHub roles?

Here are the roles a GitHub user can assume within an organization, from most to least privileged:

• Owner: the owner has complete control and full administrative access to the organization. They can supervise all the teams’ access rights to repositories.

• Billing manager: they can manage all the payment settings such as payment methods, subscriptions, and invoices.

• Security manager: they are responsible for managing the security settings across the organization. This is useful to let a security team supervise an organization with least privileges. This role is still in public beta at the time of writing.

• GitHub App manager: this is a specific role to manage the settings of some or all the GitHub Apps owned by the organization.

• Member: member is the default role in an organization. They have certain permissions allowing them to access or create repositories or projects.

• Moderator: they are regular members with additional responsibilities. They are allowed to block and unblock outside collaborators and manage interactions in a public repository owned by the organization.

• Outside collaborator: they are allowed to access one or more of the organization’s repositories without being explicitly a member of it. Useful to invite external consultants or temporary employees.

What is a team in GitHub?

Now that we’ve seen the definition of an organization and the various roles, there is another fundamental concept to grasp before diving into the best practices: teams.

Teams are groups of members that reflect the organization’s structure. They are maintained by organization owners and team maintainers who can add or remove members and give teams admin, read, or write access to repositories. Teams allow for a great level of flexibility for collaboration and integration.

An interesting feature of teams is the possibility to leverage inheritance through nested teams: child teams inherit the parent’s access permissions, and are also notified if the parent is mentioned somewhere. Imagine we have a team “Everyone” with a single child team “Engineering”,  itself with two nested teams “Frontend” and Backend” (see below). Granting Everyone to write permission to a repository means Frontend and Backend also get that permission.

Teams also have dedicated pages where you can see the members, child teams, the team profile picture, etc. and even have private discussions, which is helpful in larger organizations.

For smaller structures such as startups or small open-source projects, Teams may not be so interesting: administrating them could be more work than it is worth, especially if everyone needs to be aware of everything. But as the structure grows, it is always possible to refine the hierarchy by creating teams to hold groups of functional areas or even create communities of practice.

We are now ready for the best practices for managing GitHub teams!

GitHub Best Practices for Managing Orgs

Plan continuity

When creating a new organization, you will have a number of settings at your disposal. As you will be the first owner, it is recommended that you also assign at least one other owner. The reason is that if you lose access for one reason or another, the organization will be able to maintain ownership continuity.

Use teams

Use teams to manage access to your organization’s repositories. As mentioned earlier, teams can greatly simplify access management, especially when leveraging nested teams. Adding or removing permissions for the parent teams automatically means doing the same for the child teams. This allows you to easily manage granular permissions and control which members have access to which repositories.

Ad hoc teams are also a great way to form a dedicated team on the fly, for example, to solve a complex issue requiring members of several teams to work together.

Overall, teams greatly enhance communication in an organization.

MFA for all

MFA (multi-factor authentication) is now a basic security setting every organization should enforce. MFA adds an extra layer of security to your account by requiring you to enter a code from your mobile phone or another device in addition to your password. This makes it much harder for threat actors to gain access to your account, even if they catch a member’s password.

Make sure your GitHub data is backed up

As a best practice, it is always recommended that you have a backup and recovery plan for critical repositories and ever-changing metadata (learn why). GitHub doesn’t provide it by itself. In the event of a temporary outage—or worse—this will help ensure that you can recover everything needed to ensure business continuity.

Including a backup & restore strategy from the start is the best way to achieve peace of mind!

Use automated security tools

Getting the basics right means ensuring that basic security controls are in place to enforce your organization’s policies. In GitHub, you can enable or disable various features such as Dependency graph and Dependabot (automated dependency updates) to automatically activate them when a new repository is created.

Ensure all the repositories and pull requests are continuously scanned for secrets. Last year over 6 million secrets were accidentally pushed to public GitHub repositories! You can install the GitGuardian App from the GitHub Marketplace to monitor all your repositories in real-time and even scan their entire git history (free for public repositories and organizations with less than 25 contributors) 

Assign Code Owners

Using automated code scanning is important but manual code reviews too. Code owners are responsible for reviewing and approving code changes in a repository. They will be notified every time their own code is modified by a pull request. GitHub allows a high level of flexibility when it comes to code owners: they can be assigned a repository, a directory or even a specific file (with the CODEOWNERS file, see the docs). This can be helpful to remove confusion about ownership and ensure the smooth functioning of a team.

Periodically review access controls

As more members will be added, repositories and teams are created, permissions will need to be reviewed. The reason is that it is easy to set access permissions on an as-needed basis, and forget about them after a while. That’s why periodical reviews should be planned, to make sure no one has more permissions than they need to have. This is a basic security principle that will help to prevent unauthorized access to sensitive information. You should also have a process in place for revoking access when someone no longer needs it.

Track Progress using GitHub Projects

Use labels and milestones to organize and prioritize your organization’s issues and pull requests. Then you can keep track of teams’ progress by creating a GitHub project board. This feature allows you to create Kanban-style boards for your repositories to see what’s being worked on and what is still pending. You can also add notes and tags to your cards to keep all the relevant information in one place. Tracking progress using GitHub Projects is a great way to keep your project organized and on track.

Keep Lean Git Branches

One of the key advantages of a GitHub organization is allowing an unlimited number of developers to work on different projects simultaneously. But to make the most out of this, it is important to maintain a lean history for your projects: as such, it is recommended to always have people work on a dedicated branch for each feature or bug to avoid potential overwrites and other collaborative problems.

To keep things well organized, another recommendation is to keep the graph of branches as simple as possible. To achieve that, developers should be encouraged to rebase their branch on the main branch. Rebasing can help resolve merge conflicts more efficiently and make it easier to track changes and keep your codebase up to date.

Finally, another good practice is to squash commits before merging. Squashing commits is a way of rewriting the commit history before you share it with your team. Only the most important commits’ names should be kept since commits are like milestones in the history of a git project. It also makes it easier to associate a bug with a specific commit when it comes to debugging.

Summary

GitHub organizations are a great way to manage code and collaborate with teams. To ensure the success and security of your projects, it’s important to establish some habits and practices for your organization. As the owner, you can create nested teams, set security policies, and assign code owners to help manage your organization. And if your team members can take responsibility for squashing commits, rebasing branches, and testing code, everything will run smoothly.

By implementing these best practices, you can effectively manage your GitHub organization and ensure the success and security of your projects.