🏷️ Automated label checking for GitHub pull requests.
required-labels enforces label rules on your pull requests. We use this at Dimagi to alert our product and design teams of external-facing changes we are making to our code.
Check it out in action here.
There is also a longer write-up on this project here.
You can set customized label requirements for your PRs to enforce particular team workflows with lists of "required", "banned" or "at least one" labels. For example:
- Your team requires all PRs to get sign-off from your Architecture and UX teams before being merged
- Set
REQUIRED_LABELS_ALL
toux-signoff, arch-signoff
. This will ensure that theux-signoff
andarch-sigoff
labels have been added to that PR before allowing it to be merged.
- Set
- Your team uses a certain label to flag something as "work in progress" that should never be merged until the label is removed.
- Set
BANNED_LABELS
towip
. This will prevent any PR with thewip
label from being merged.
- Set
- Your SRE team requests that all PRs get marked as either high- or low-risk before being merged, so that if the site goes down or something is wrong, they can quickly scan for changes that developers anticipated might have adverse effects.
REQUIRED_LABELS_ANY
:high-risk,low-risk
. This will require at least one ofhigh-risk
orlow-risk
to be added to the PR before it can be merged.
Click the following button to deploy this app to heroku (you'll need a heroku account):
You'll be presented with a set-up screen.
Enter the name for your app. Something like your-required-labels
.
Set up the required labels (comma separated):
REQUIRED_LABELS_ANY
: At least one of these labels should be present on all PRsREQUIRED_LABELS_ALL
: All of these labels must be present on all PRsBANNED_LABELS
: None of these labels can be present on all PRs
Enter the credentials:
GITHUB_TOKEN
: A github user TOKEN for user that will post the status. We suggest you create a dummy github user for this purpose. This user must have permission to write to the repo in order for it to post a status.
OR
GITHUB_USER
: The username of the GitHub user that will post the status. We suggest you create a dummy github user for this purpose. This user must have permission to write to the repo in order for it to post a status.GITHUB_PW
: The password for this GitHub user.
Note: The application will use GITHUB_TOKEN first if defined and will fall back to GITHUB_USER and GITHUB_PW if not.
Click "deploy app". The app will deploy.
When completed, you can click "Launch App" and it will take you to an information screen which lists all of the label settings.
Next, you should set up your repo.
In the heroku dashboard for your app, click Settings
then Reveal Config Vars
. Here you will be able to update the label settings and github credentials at any time.
- python 3
- pip
- Clone this repo:
$ git clone git@github.com:dimagi/required-labels.git
- Install the dependencies
$ pip install -r requirements.txt
- Create a config file
$ cp custom.conf.template custom.conf
Then modify custom.conf
with your own settings.
Default behavior is to source this file from project cloned directory.
You can source a custom file path using CONFIG_FILE
environment variable.
$ export CONFIG_FILE=/some/path/to/config.conf
You can also set REQUIRED_LABELS_ALL
, REQUIRED_LABELS_ANY
, or BANNED_LABELS
along with GITHUB_USER
and GITHUB_PW
directly as environment variables:
$ export REQUIRED_LABELS_ALL=required-label-name,other-required-label-name
$ export GITHUB_USER={username}
$ export GITHUB_PW={password}
- Run the app
$ gunicorn main:app
In the GitHub repository you want to enable this service, click Settings
-> Webhooks
-> Add Webhook
. Then enter the following settings:
- Payload URL: The URL to your heroku app. e.g. https://your-required-labels.herokuapp.com
- Content Type: "application/json"
- Let me select individual events: Set this to "Pull Request" only.
- Active: Leave this selected.
Now, a new "checker" should show up when creating a new pull request.
In the Collaborators & teams
settings page, make sure the user who you set up earlier has at least Write
permissions on the repo.
$ python -m unittest -v