Branch Protection At Scale Solution

General details

I have given the customer an imaginary name.

Company Name: Integrity Plus Inc.

Department: Security and Compliance

GitHub Organization: integrityplus

The solution was prepared by Ayodeji Ayodele , no external resources were used.

Problem Statement

• Ensure proper code reviews for all code being added to our repositories.
• Looking for the best way to do it at scale.
• Using OOTB settings is most preferable.

Solution Approach

In addition to GitHub which serves as the primary service for storing and managing code, two main platforms were used in the solution.

Platform	Purpose
Azure Logic App	Web API for receiving webhook deliveries from the GitHub organization. Visit the src directory for documentation on architecture and how to deploy.
Azure Boards	Project tracking and management

Setup a GitHub organization

• Create a new organization: This is the first natural step to take, as this customer is a business and not an individual. Organizations are shared accounts where businesses can collaborate across many projects.
  • Organization name - integrityplus
• Invite people, create teams and apply relevant roles:
  • Invite people: I registered one additional github user @ayooutlook and invited it into the new organization. At least two users is needed in order to simulate different roles and code review approvals.
  • Create teams: I created a team @integrityplus/security-and-compliance and granted it the security manager role. Members of a team with the security manager role have only the permissions required to effectively manage the security for the organization. Read more

Secure the organization

It is important to configure security features in the organization to complement the specific security requirements in the customer's brief. The following features were enabled in the organization:

• Two-factor authentication: Zero-trust security is essential to ensure only the right people have access to the customer's code. Two-factor authentication is enabled.

• Code security and analysis

  • Enable dependency graph
  • Enable dependabot alerts
  • Enable dependabot security updates

Create a .github repository

The .github directory is used to store community health files as well as the organization profile. The following were added:

• SECURITY.md to serve as the default security policy for every new repository created in the organization.
• ISSUE_TEMPLATE/branch-protection-issue-template.md to serve as the content template for the issue that would be automatically created in the repository once the branch protection has been applied on the default branch.
• profile/README.md to give a profile description of the organization.

Implement default branch protection

This was achieved with two components, a webhook to listen to organization events, and a custom web API to receive the delivery of the webhook's payload and orchestrate the application of the branch protection as well as create the issue in the repository.

Web API

A separate documentation is dedicated to the Web API. Please visit the src directory.

Webhook

Before creating the webhook, the URL of the API needs to be ready. Therefore, you should already deploy/host the web API before carrying out this step.

The webhook was created with the following properties:

Property	Value
Payload URL	Web API endpoint URL
Content type	application/json
SSL verification	Enable
Events to trigger	Branch or tag creation (only 1 event)

For a step-by-step guide on how to create a webhook, visit GitHub Docs.