org-apex/github-repo-auto-protect

Languages	Products	Tools	Description
Java, Spring boot, Azure Fucntions	GitHub, Azure	Maven, Ngrok, Azure CLI	This is a sample application to showcase how to automatically enable branch protection when every new repository created under GitHub Organization

GitHub Repository Branch Auto Protection

This is a sample application to showcase how to automatically enable branch protection when every new repository created in a GitHub Organization.

This application is using GitHib organization webhooks to send an HTTP POST payload to a third-party service that uses the GitHub REST API to programmatically enable protection on the default branch of the newly created repository.

The third-party service is implemented using Java Spring Boot as a serverless Azure Cloud function.

:bulb: Tip: You can use ngrok or similar solutions to expose the service directly from an http server running in localhost.

:bulb: This project uses the GitHub API For Java library to manage GitHub resources.

:memo: Note: The third-party service can be implemented in any programming language and deployed to any platform as long it is able to receive events sent by the Organization webhook. GitHub provides the Octokit library in Ruby, .Net and Javascript. Third-party libraries are also available to support other languages.

How It Works

This block diagram shows how the Webhook configured at an organization level sends create repository events to an Azure Serverless fucntion. And Azure Serverless fucntion can enable the protection on default branch on the created repository.

This sequence diagrams depicts how the sequence steps needed to enable auto protection on the default branch when a new repository is created.

Getting Started

These instructions will guide you on building and deploying the Azure Cloud Function and configuring the GitHub organization webhook.

Prerequisites

GitHub personal account
Java Developer Kit, version 11
Apache Maven, version 3.0 or above - For building and running locally
Azure Free Account account
Azure Functions Core Tools version 3.0.13901.0 or above

GitHub Personal Access Token

GitHub personal access token is needed to enable communication between the Azure cloud function and the GitHub API

Please follow the documentation to create a GitHub personal access token.

:warning: Save the personal access token in a safe place, it will be used later in this guide.

In this example scope is provided at workflow level Personal Access Token Scopes

See GitHub's documentation to learn more about scopes.

Installation

Install below software if it's not pre-installed on your local computer. Install the Maven Install the JDK Install the Azure CLI Install the Azure Functions Core Tools Install ngrok agent (Optional), To expose local server ports to the Internet.

Clone the project: bash git clone https://github.com/org-apex/github-repo-auto-protect.git
Configure the project to use your own resource group and your own application name (it should be unique across Azure)
- Open the pom.xml file and customize the resourceGroup and appName properties
- This project uses the Maven Wrapper, so all you need is Java installed.

Build the project: bash ./mvnw clean install -DskipTests=true

Setup

Azure Functions

Once the application is built succesfully, you can run it locally using the Azure Function Maven plug-in:

bash ./mvnw azure-functions:run

Spring boot azure fucntion webservice will start run succesfully on your local computer. In this example it's running on port 7071. You will see maven logs like:

Deploying to Azure Functions App

Deploy the application on Azure Functions with the Azure Function Maven plug-in: :memo: Note:, make sure Application running locallys has been stopped.

bash ./mvnw azure-functions:deploy

After a few seconds, will create the resources in your Azure account. This may take some time.
Once the process is finished a summary of the changes will be displayed on your terminal, make note of the API Gateway endpoint URL, it will be used to configure the GitHub Organization webhook.
To validate that the deployment was successful, open your browser and navigate to the Azure portal and go to Fucntion App > Functions

Azure Portal :: Servlerless Functions

Github webhook setup

Once the third party application has been deployed, we are ready to configure our GitHub organization webhooks to notify the application when a new repository has been created.

Open your browser and go to GitHub
If you have not created a GitHub Organization yet, create one
Go to your GitHub organization settings page and select Webhooks.
Setup the Azure serverless function service url https://apex-githubpoc-function.azurewebsites.net/api/handler to Github organization Webhooks.
Select application/json in the Content type field.
Enable SSL verification.
Select individual events to trigger the webhook.
- Uncheck the Pushes option.
- Check the Repositories option.
Check the Active option.
Click the Add webhook button.

Local setup

(Optional) You can expose the local running service to internet:

You can run ngrok agent on your local computer

ngrok http 7071

:bulb: If application is not running locally, run it locally using the Azure Function Maven plug-in:

bash ./mvnw azure-functions:run

After ngrok successful start, you will service exposed to internet as:

Setup the ngrok URL for Azure serverless function service https://b949-24-28-109-133.ngrok.io/api/handler to Github organization Webhooks. :bulb: For updating the webhook in Github, follow the steps under the section Github webhook setup

Testing

Once the GitHub Organization webhook is configured to deliver events to the Azure Serverless function we can go ahead and test the use case.

Login to GitHub and go to your Organization page
Create a new repository
Type a name in the Repository name field
Make your repository Public
Click on the Create repository button
After a few seconds reload your repository page and you should see the following:
- A new commit in your repository
- A new README.md, CONTRIBUTING.md, and LICESNSE.md files are created in the root of your repository.
- A new issue created in your repository
Go to your new repository settings, then select branches from the left and you should see that branch protection rules were added to your default branch