Configuration¶
Labelbot uses two configuration files, one for storing GitHub Access Token and second one for storing labeling rules.
Configuring labels¶
Labelbot needs a config file containing rules according to which it should add labels to analyzed issues. The example rules files looks like this:
.*README.*::Documentation
file::Test
foo::bar
First item in each line is a python regular expression or simply a string. The second item is a label name to be added to the issue.
Note
Setting label colors is planned, but currently not possible.
Configuration file can be placed anywhere as long it is accessible by Labelbot.
Also it is necessary to pass to Labelbot using -u, --rules-file
option. In
case this option is not specified, example config file is created and used. This
file is stored in user configuration directory, for example on Linux
in ~/.config
directory. It can be directly edited.
Note
For rules configuration file change to take effect, Labelbot needs to be restarted.
Obtaining and configuring GitHub Token¶
To run your own instance of Labelbot, you will need a Personal GitHub Access Token which will allow your bot to use GitHub API. For this purpose, we advise registering a new GitHub bot user. Such user is not different in any mean, but it will allow you to manage which repositories should be labeled or not.
Note
Bot users should be clearly marked as bots (you can use ‘About me’ section) and should point to accounts of their owners. This will prevent you from your bot account being deleted as a duplicate account.
Once you’ve created your bot account and logged in to GitHub, navigate to Personal access tokens settings page. Select ‘Generate new token’ and tick ‘Repo’ scope in the displayed form. Fill in token description and submit the token generation. After that, copy the generated token - it won’t be visible again!
Once you have your token, you can pass it to Labelbot using -g, --github-token
.
Alternatively you can save it to a configuration file and pass it’s path to Labelbot
using -t, --token-file
. Also, you can export GITHUB_TOKEN
environment
variable or rewrite default configuration file in user configuration directory.
On Linux, that means ~/config
.
Setting up GitHub webhook¶
Labelbot can run in two modes - console and web (See deployment-and-running). Web mode allows the Labelbot to react to changes in repositories in real-time and also reduces the overall load of the Labelbot. However, additional configuration is required.
Labelbot in web mode uses GitHub Webhooks functionality. For details on how to deploy Labelbot in web mode, see deployment-and-running. This chapter describes the steps needed for Webhook configuration.
To setup your own webhook, following steps are required:
- Add your GitHub bot user as an collaborator to the project you want to label.
- Create a new webhook in Webhooks Settings page in your repo with your
hook’s Payload URL (e.g. https://labelbot-api.herokuapp.com/hook) and
issues
andissue comment
events allowed. - Set
WEBHOOK_TOKEN
environment variable in your deployment environment corresponding to the secret token you used during webhook creation.