Oh, you thought this was a democracy? Guess again... in this kingdom, branches are micromanaged and admins have less power Β―\_(γ)_/Β―
Branch Dictator will enable Branch Protection for all new org repos that are created with public visibility and are created with an initial branch (via the addition of a README.md
, LICENSE
, and/or .gitignore
when the repo is created).
Interested in using Branch Dictator to keep your kingdom in line? Let's get started.
The first step to setting up your own instance of Branch Dictator is to fork this repo. It's designed to be used within an org, so make sure to fork this repo into an org, not under a personal account. If you don't have an org, you can create one for free!
This app uses GitHub Secrets in conjunction with GitHub Actions to perform all CI and CD actions. After forking into your org, head over to your app's Secrets and set the following values:
This project uses Codecov for coverage analysis. Navigate to codecov.io
and follow the steps to link your org and repo. When you're done, you'll be provided with an API key.
This app uses a GitHub Action to deploy to Heroku; if you'd prefer to use your own hosting solution, make sure to remove that action and ignore the following sections. If you'd like to use Heroku, make sure to create an account before continuing if you don't already have one.
Create a new Heroku Authorization with a description of Branch Dictator API Key
or something similar, leave Expires after (seconds) blank, and hit Create.
Choose a name for your app in Heroku. This name must be unique across all of Heroku, so make sure to use something like your GitHub org name to make it unique (e.g., some-org-branch-dictator
).
The email account associated with your Heroku account. This can be found in your Heroku Account Settings.
This app has a handful of environment variables. The instructions below are for Heroku, but other cloud environments will have a similar method of setting them.
Eventually these values will be stored within the repo's secrets, but for now you'll need to set them manually. After creating your app, navigate to your app's Settings tab, scroll to Config Vars and set the following values:
Create a Personal Access Token with a note of Branch Dictator
(or something else of your choice) and enable just the repo
scope (NOTE: when selecting repo
, all the children of the repo
scope will automatically be enabled) and click Generate token.
This will be used within the Configuring the Webhook section below, but can be whatever text you'd like (just make sure it's not blank!).
Set this value to production
to ensure the app behaves as expected and will not start if certain required variables are not present.
This project also uses LGTM for codescanning. If you'd like to use LGTM within your project, create an account and follow the steps to link your repo and install the LGTM app within your org.
Once your app is deployed and ready to go, you'll need to create a webhook to ensure the app is notified when repos are created. Head to your org's settings page and navigate to the Webhooks section. Click Add webhook and use the following values:
- Payload URL:
{your-app's-URL}/api/webhook/repository}
(e.g., https://my-branch-dictator/api/webhook/repository) - Content type:
application/json
- Secret: Your secret from the
WEBHOOK_SECRET
section above - SSL verification: β
Enable SSL Verification
- Which events would you like to trigger this webhook?:
Let me select individual events
- uncheck all except:Repositories
- Active: β
Click Add webhook and wait for the response from your app. If you see anything but a 200
status code on the response, make sure to click back into the webhook settings, scroll down, and click on the Response
tab to see more info. If you see a 200
, you're all set! To make sure things are working, create a new public repo with a README
and then check the repo's branch protection settings and validate that an issue was creted notifying you of the change to the settings.
Project environment variables should first be defined in .env.sample
without real values for their data (that file is tracked by git). After cloning, make sure to duplicate .env.sample
as .env
and then fill in all required variables.
This project is reliant on the installation of the following dependencies:
- Node (LTS) (v12.0+)
After downlodaing the dependencies above, install all NPM dependencies by running npm i
.
The best way to start the app and work on it is by using npm run dev
, which will start the app and then restart the app whenever a TypeScript file changes. After modifying a non-Typescript file, restart the app by typing rs
into the same terminal you ran npm run dev
from and then hitting return.
After the app starts, it will be accessible on localhost:3000
(unless the port was modified via .env
).