Help
cancel
Showing results for 
Search instead for 
Did you mean: 

Best Practices for Organizations

GitHub Staff

GitHub is a powerful platform for individuals and organizations to discover, share, and contribute to code. The sheer volume of information in GitHub can, at times, be  overwhelming, especially as the number of users and repositories grow within an organization.

Organization administrators want to provide their users the best possible collaborative experience while meeting their security requirements and limiting their maintenance effort. To that end, I'd like to share what we at GitHub have found to be the best practices for organizations to:

 

  • Secure users and content
  • Organize users and content
  • Automate maintenance and compliance workflows


Best practices for securing users and content

While many people associate GitHub with open source code, organizations large and small trust GitHub with their proprietary code as well as their contributions to open source. In order to keep organization members and code secure we recommend the following:

Require two-factor authentication (2FA)

Organization owners can (and should) require all members and outside collaborators to have two-factor authentication enabled on their accounts. GitHub supports 2FA via Time-based One-Time Password (TOTP) apps like Google Authenticator, which can then (optionally) leverage Fido U2F compliant hardware keys.

GitHub also currently allows configuration of SMS-based 2FA. As SMS-based 2FA has proven vulnerable to a number of attacks we highly recommend utilizing TOTP.

We also recommend that you give your organization's members a bit of advance notice before requiring 2FA. As soon as you require 2FA for your organization all members and outside collaborators who have not set up 2FA for their accounts will be immediately removed and their access to forks of your repositories will be broken. If a few users fail to enable 2FA before you require it, fear not. Their privileges can be reinstated within three months of removal.

Enable and require SAML authentication (Business)

If your organization is part of a GitHub Business Cloud plan you can, and should, configure, and require, SAML authentication for organization members.

With SAML authentication enabled, your organization can enforce enterprise account policies (such as password age, minimum password requirements, web session timeouts, and enterprise 2FA) on your organization members' access to your content.

Requiring SAML authentication will automatically remove all members from your organization that have not yet signed in via SAML. As such, before requiring SAML authentication for all organization members, we recommend first configuring your SAML provider and leaving an "opt in" window for organization members. During this time you should encourage all members to sign in via SAML so their accounts are not removed from the organization when SAML authentication is enforced.

As with 2FA, users removed due to a lack of SAML can have their privileges reinstated within three months of removal.

Note: Outside collaborators added to a repository will not be required to use SAML to authenticate (they are `outside` of your organization). If you want to require SAML for outside collaborators they will need to be invited to be members of the organization and have an identity in your SAML provider. Integrations are available to help if you wish to explicitly control outside collaborators and/or disallow them all together. See the probot section of this article for more information.

Default repository permissions

GitHub's value to an organization increases when developers are able to discover, use, and contribute back to code. This holds true for Open Source and proprietary code. To promote greater visibility and reuse of internal code, GitHub recommends making your private code as open as possible. For many organizations, this means all organization members have at least read-only access to all code. This level of access can be easily granted by setting the organization's default repository permissions to 'read'.

 

 

43146082-07cafe9e-8f26-11e8-867b-7cf2212fc4c7
For greater collaboration on private repositories consider granting `write` permissions as the default in combination with appropriately configured branch protections in each repository. This will enable members to create branches in repositories and propose changes through pull requests, while not allowing them to modify production-ready code. This is the preferred method for organization members to collaborate on private code as:

 

  • forks must exist in another namespace (outside of the organization) and therefore:
    • do not have access to any of the organization's teams for collaboration and permissions management
    • require the owner to add and remove collaborators on their own
    • do not have access to an organization's configured integrations
  • forks are not indexed for searching


If your organization absolutely cannot provide members at least read-only access to all repositories (perhaps you have contractors in your organization who should not be able to see everything, or perhaps a subset of your code is super secret and on a need-to-know basis) you can set the default permission to 'none' and explicitly grant access to repos using teams and outside collaborators. If this is the case, we recommend using teams to create a similarly "open" experience and will cover how to do so in the teams section of this article.

Repository visibility

Most organizations have explicit policies and procedures for determining which repositories can be contributed to the open source community. On GitHub.com any repository that is 'public' is available for the world to see and use. GitHub provides organization administrators the ability to prohibit organization members from changing their repository's visibility.

With this enabled, only organization owners will be able to change a repository's visibility.

Looking for a way to automate the checking and enforcement of repository visibility? Check out the probot section of this article to learn more.

Best practices for organizing users and content

Simplify team management with nested teams

Most organizations use teams to manage their members' access to repositories. Managing large numbers of teams is simplified when using nested teams. Each child team inherits its parent's access permissions and members of child teams receive notifications when the parent team is @mentioned.

Promote openness across your organization with an 'all employees' team

As mentioned in the above default repository permissions section, repositories should be as open as possible to promote sharing, reuse, and contribution across the organization. If a default permission of at least `read` is not possible for all repositories we recommend creating an `all-employees` team and granting it appropriate access to all but the most top-secret repos. This way, all employees of your organization can benefit from an open environment, while the access of non-employee members of your GitHub organization can be more heavily restricted.

Leverage internal expertise with ad-hoc teams

Most businesses that use GitHub inherently map their team structure to their organization chart to provide appropriate levels of access. By itself this structure can leave blind spots as members of an existing team may not by themselves have the expertise necessary to solve certain problems. Ad-hoc teams are supplemental to those teams used to manage permissions and are designed to let organization members self-organize around specific disciplines and topics.

When combined with team discussions, ad-hoc teams create:

 

  • spaces for internal development communities to organize
  • informal, self-sustaining, internal support networks
  • opportunities to leverage talent and expertise from across an organization
  • new ways to promote knowledge transfer


Topics

Topics help organize your organization's repositories. Many open source communities and repositories use topics to categorize repositories by language and application type. The `electron/electron` repository is a great example of this:

 

43146325-a0e5efc6-8f26-11e8-9e2d-c9962d559df7
Teams within organizations desire an easy way to categorize repositories by various criteria, including:

 

  • framework(s) and languages used
  • team(s) responsible for maintaining the repo
  • system(s) the repos roll up to


Topics are a great way to achieve this as well. Simply add topics to your repositories such as `Java`, `Team-Ice-Cream`, and `order-management` to your repositories. When searching GitHub, results containing your topic will be returned. From the main search bar simply scope your search to your organization by prefixing your search with `@my-organization ` to see topics and other results matching your query.

Labels

Most GitHub users are familiar with the ability to use labels to categorize their issues and pull requests. However, as project size and scope grow, the number of labels in use can become overwhelming. As the number of labels in use grows, we recommend creating a taxonomy of labels coded by both text and color.

The labels used by the Electron project demonstrate successful use of this technique. Note how all labels having to do with a component use a light orange color and all the issues noting bugs use a bright yellow. This allows anyone looking at a long list of issues or pull requests to quickly understand what an individual issue or PR is about by merely noticing the label color. More detail is always available by reading the label.

 

43148333-aecee508-8f2a-11e8-8077-7f8e7c9db7ee

 

Automate compliance and common tasks with Probot

Probot is a framework for building GitHub Apps to extend and automate activity in GitHub. A number of common organizational tasks can be automated with Probot. Probot apps can be installed on individual repositories or for all repositories in an organization. Installing them on all repositories enables users to take advantage of each app's capabilities by simply adding the proper configuration file(s) to the repo.

Here are some of the Probot apps most commonly used by organizations:

Enforce and track repository settings

probot-settings allows repository settings to be defined in a .yml file. If an administrator modifies the settings to be something other than what is defined in the file, probot-settings will change them back. This provides enforcement of repository settings and empowers non-administrators to propose changes by simply opening up a pull request.

Keep the conversation moving

probot-stale helps keep your list of open issues and pull requests from growing too long by calling attention to those that have not seen activity for a defined period of time. If they remain inactive, probot-stale will close them out for you. And, if there are special cases for long-running issues and PRs, probot-stale can be configured to ignore threads with specific labels applied.

Set follow up reminders

Sometimes we all need a reminder to come back to an issue or pull request. probot-reminders will do just that. Just type a `/remind me <timePeriod>` command in plain language to have probot-reminders helpfully create a new notification in the thread after the specified time has elaspsed.

Prevent public repositories

While GitHub organization owners can prevent users from changing the visibility of repositories, users can still create new public repositories. prevent-public-repos lets organization owners prevent the creation of any new public repos by immediately changing new public repos in the org to private. It also includes the ability to allow a configured list of repos to remain public, enabling an open-sourcing workflow that is documented and enforced by code.

Limit outside collaborators

Administrators may wish to strictly limit or completely exclude any outside collaborators from their organization. remove-outside-collaborators can be configured to automatically remove all outside collaborators as soon as they are added. It can also be configured to only allow those outside collaborators specifically defined in a configuration file.

Need help taking full advantage of these practices to organize and secure your content and users? Contact our support team, we're happy to help.