Skip to main content

Automatically label GitHub issues based on regexp rules.

Project description

Travis Status Documentation Status


Application will label issues on GitHub based on the issues’ title, contents and/or comments. Labelling is determined by a set of regular expression rules.


For up-to-date documentation, refer to documentation.

pip installation

pip install gitbot

Also installs a gitbot executable.

Running tests

  • Clone this repository and run python test in the root directory. By default the tests that need authentication will be replayed from stored betamax cassettes. This should be enough in most cases.
  • To re-generate betamax cassettes
    • have AUTH_FILE environment variable filled and pointing to auth.cfg file. (see auth.cfg.sample for example contents)
    • have file auth.cfg filled with credentials and run python test in the root directory
  • Download pip package via pip download gitbot. Then unzip, cd into the directory and run python test. The same testing details as described above apply.

Building documentation

To test and build the Gitbot documentation, do the following: - Change folder to docs. - Run pip install -r requirements.txt. - Run make html (or make.bat html on Windows) to build the documentation, or - Run make doctest (or make.bat doctest on Windows) to run documentation tests.

Operation modes

There are two ways of running the bot:

  • Console - actively polls GitHub for new issues and based on given options labels them. Run as console (...)

  • Web app - passively listens for GitHub’s webhooks informing about new or changed issues. The endpoint listening for GitHub calls is /callback. May be run from command line as web or deployed as a WSGI application using this wsgi config:

    import sys path = '/path/to/script/folder'
    if path not in sys.path: sys.path.append(path)
    from web\_listener import app as application

Quick oneliner

python ./ console -i 30 -d default-tag --no-comments --no-process-title melkamar/mi-pyt-test-issues Will process only body of the issue report. Any further comments nor the title of the issue will not be matched against rules.


Rules are located in file rules.cfg by default. Any other file needs to be passed as a command line option. The format for rules is regexp=>desired label.


Bot needs an authentication token with permissions to label issues. Token is stored in auth.cfg file by default. See the example file for details.

For web usage, the webhook secret has to be set in auth.cfg as well as the repository to be handled. The script will not do anything if the security check fails.

Detailed parameters for console mode

Usage: console [OPTIONS] REPOSITORIES...

   -a, --auth TEXT Authentication file. See auth.cfg.sample.
   -v, --verbose Much verbosity. May be repeated multiple times. More v's, more
   -r, --rules-file TEXT File containing tagging rules.
   -i, --interval INTEGER Interval of repository checking in seconds. Default
      is 60 seconds. -d, --default-label TEXT Label to apply to an issue if no
      other rule applies. If empty, no label is applied. Defaults to no label.
   --process-title / --no-process-title Should the title of the issue be
      matched against the rules as well? Defaults to true. --comments /
   --no-comments Should comments be also matched against the rules?
      Defaults to true.
   --closed-issues / --no-closed-issues Should closed
      issues be still processed? Defaults to false.
   --skip-labelled / --no-skip-labelled Should issues that are labelled already be skipped?
      Defaults to true.
   --remove-current / --no-remove-current Should the
      current labels on an issue be removed if a rule matches? Defaults to
   --help Show this message and exit.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution (68.1 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page