How to use Gitbot¶
Gitbot may be run in two ways:
- Console mode
- Runs as a console application, all issues are re-scanned and processed every couple of minutes (interval customizable). Easier to set up, no requirement on setting up GitHub (aside from credentials).
- Web server mode
- Runs as a web application. GitHub repositories that should be processed need to be set up with GitHub web hooks. Application can either be run using embedded webserver, or deployed as s WSGi application.
Labels that will be applied to issues are defined in a rules file (see Labelling rules).
Console mode¶
Gitbot in console mode is started as gitbot console [OPTIONS] REPOSITORIES...
, where:
REPOSITORIES
is whitespace-separated list of GitHub repositories to process, e.g.melkamar/gitbot foo/bar
.- Gitbot must have sufficient permissions to read the repository and push labels. See Authentication.
OPTIONS
are following:-a, --auth TEXT
- Authentication file. See auth.cfg.sample.
-v, --verbose
- Much verbosity. May be repeated multiple times. More v’s, more info!
-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 false.
Web server mode¶
Web server mode may be run from console with embedded server, or as a WSGI app. Both are described at the end of this section.
In order to have web server Gitbot working, the following is necessary:
- Publicly accessible (routable) server.
- Correctly set up authentication token and webhook secret (see Authentication).
- Web hook set up for a repository for which the token has sufficient permissions (see GitHub web hooks).
Running with embedded server¶
Embedded Gitbot server is started using gitbot web
. Unlike console mode, it is not currently possible to configure
issue processing options.
Running as WSGI application¶
To run Gitbot through a WSGI server, the following config is used:
import sys
path = '/path/to/script/folder'
if path not in sys.path:
sys.path.append(path)
from web_listener import app as application
GitHub web hooks¶
In order to use Gitbot as a passive web server, GitHub needs to notify it via a HTTP POST every time an issue is created or edited. To do that, go to your GitHub repository and navigate to Settings > Webhooks > Add webhook, and fill in the following information:
- Payload URL
- URL where the notification should be sent. Should be
<gitbot-address>/callback
, e.g.https://example.com/callback
.
- Content type
application/json
is what we want.
- Secret
- Enter the same string you set up in the authentication file (see Authentication for more details).
- Which events will trigger this webhook?
- Choose
Let me select individual events
>Issues
.
GitHub will now send a notification every time an issue is created or edited and Gitbot will react to it. Neat.