Jeeves is an automated report generator for Jenkins CI. It generates an HTML report using Jinja2 templating and sends it out over email using Python's smtplib.
Create a file named config.yaml based off config.yaml.example with the following fields filled in:
- jenkins_url: URL of your Jenkins server
- job_search_fields: Filter of Jenkins Jobs to included in report, e.g. DFG-ceph-rhos. To search for multiple fields, seperate them by comma, e.g. DFG-ceph-rhos,DFG-all-unified. Allows for regex searches as well, e.g. ^DFG-ceph,rgw$
- filter_param_name: Optional field that instructs Jeeves to skip any build that lacks the corresponding value of the given build parameter. Must be used on in conjunction with filter_param_value
- filter_param_value: Optional field that instructs Jeeves to skip any build that lacks this value for the corresponding build parameter name. Must be used in conjunction with filter_param_name
- filter_version: Filter of the OSP versions to included, it's a regex e.g. '1{1}[0,3,6]{1}.{1}\d{1}|1{1}[0,3,6]{1}(?=\D+)'
- cause_action_class: Optional field that instructs Jeeves to skip any build that does not satisfy the 'cause action' which started a job build. Possible values are: timer, user, or upstream
- bz_url: URL of your Bugzilla, e.g. https://bugzilla.redhat.com/
- jira_url: URL of your Jira, e.g. https://projects.engineering.redhat.com/
- jira_username: Your Jira username. If included in config.yaml basic auth method is used to authenticate to jira, otherwise Personal Access Token is used and jira_token has to be set.
- jira_password: Your Jira password. Has to be set together with jira_username field.
- jira_token: Your Jira Personal Access Token.
- certificate: CRT file to authenticate with Jira server
- smtp_host: SMTP host of your email
- email_subject: Subject of your email report
- email_from: The email address of the sender
- email_to: Email address you would like to send your report to. To send the report to multiple emails, seperate them by comma, e.g. recipient1@website1.com,recipient2@website2.org
- email_to_test: Email address to send test reports to (note: this field is only required if you run Jeeves with the
--test-emailflag) - supported_versions: Optional OSP versions list that instructs Jeeves which OSP versions are supported, and should appear in the report. Default versions are 13, 16.1 and 16.2
- stage_logs: Optional dict field that instructs Jeeves how to build URLs to a log files for a corresponding failed build stage
If you wish to use a different configuration file, you can specify it as a command line argument.
Create a file named blockers.yaml based off blockers.yaml.example with each UNSTABLE and FAILED job containing two sections - 'bz' and 'jira' - and a list of the blocker IDs. 0 indicates blocker bug/ticket is not on file (either doesn't exist or hasn't been created yet).
If you have a blocker for a job that is neither a Bugzilla bug or a Jira ticket, you may add a section to your blockers file called 'other', with each item having two fields - 'name' and 'url'. Both fields are optional - you can include one, the other, or both.
You can also add information about build number for FAILED, UNSTABLE, and NO_KNOWN_BUILDS builds. If you record the build number for which you have registered the issue, then you can speed up the review process by knowing if that ticket is still "current". This can be very helpful when a build starts to work again, but the blocker file is not updated. Then next time it fails, the last issue registered for that job pops up again. It can take you some time to figure out that it's not relevant anymore. But if you have build number, then you see "99" as your current build number and that the issue was registered to build "80" then you are pretty sure it's outdated.
If you wish to use a different blockers file, you can specify it as a command line argument.
You can define "owners" for a job in blockers.yaml for use with reminder mode. To do so, simply add an "owners" subfield to a job with one or more emails. You can see some examples of this in blockers.yaml.example.
$ ./jeeves.py [-h] [--config CONFIG] [--blockers BLOCKERS] [--preamble PREAMBLE] [--template TEMPLATE] [--mode {report,remind}] [--no-email] [--test-email]
For a base run, simply run $ ./jeeves.py using the --config and --blocker flags if needed as detailed above. For details on the additional flags avaliable see below:
- To add a "preamble" to the report, add
--preamble <preamble file>. The file should be written in HTML.- This flag will be ignored if Jeeves is run in "reminder" mode
- To use a different template for the report, add
--template <template file>. The template should be in the templates directory.- This flag will be ignored if Jeeves is run in "reminder" mode
- To change which run mode Jeeves will use, add
--modealong with the run mode you wish to use- Note that running Jeeves in "remind" mode will override the usage of both the
--no-emailflag and the--test-emailflag
- Note that running Jeeves in "remind" mode will override the usage of both the
- To only save report to the 'archive' folder, and not send an email, add
--no-email - To send report to email specified in
email_to_testfield, add--test-email- Note that running Jeeves with the
--test-emailflag will not save the report to 'archive' folder - As such, running Jeeves with both the
--test-emailand--no-emailflags will result in no report being saved and no email being sent
- Note that running Jeeves with the
By setting values in config.yaml for both filter_param_name and filter_param_value, Jeeves will automically skip any Jenkins builds that lack the given build parameter and value and search for the next latest completed build. Note that this is done by decrementing the build number Jeeves searches for until a build with the given parameter and value is found. Make sure your Jenkins jobs have a linear build history without missing builds if you intend to use this feature.
If you don't wish to use this feature, simply omit the two fields from your config.yaml file and Jeeves will simply use the last completed build for a given job.
Jeeves has a reminder mode that will send an email to "owners" of jobs in Jenkins that have "UNSTABLE" or "FAILURE" status. You can add as many "owners" as you would like to a given job. You can see some examples of this in blockers.yaml.example
Jeeves has an option to add URLs to a report which point to one of more log files for a corresponding failed build stage. Log files are mapped to the stage based on the stage_logs dict defined in config.yaml. In
config.yaml.example you can find some stages already mapped to logs files. Use it as a reference on how to map logs to your reports. A single stage can be mapped to single or multiple log files. It is not required to map all stages from a job to log files. Jeeves will skip adding URLs to stages which are not defined in the stage_logs.
- PyYAML for parsing config YAML
- Jinja2 for generating HTML
- Python Jenkins for interacting with Jenkins
- python-bugzilla for interacting with Bugzilla
- jira-python for interacting with Jira
To install packages run:
$ pip install -r requirements.txt
It is recommended you do this within a virtual environment.
Jeeves follows a set of PEP8 standards in the interest of code clarity and consistency. These rules are enforced with the flake8 library. Configuration for linting resides in the .flake8.ini file.
To run linting simply run the flake8 command within the Jeeves directory.
Jeeves has a small but growing test suite driven by pytest. Currently all tests reside in the tests directory.
To run tests simply run the pytest command within the Jeeves directory.
Please see contribution guidelines in CONTRIBUTING.md
Jeeves was designed for use by Red Hat OpenStack QE and the organization's production CI environment - while the project can be used for other Jenkins environments, it may require some tweaking to work as expected.