README

# Simple script for verifying Cockpit pull requests.

Hubbot is simplistic and not polished at all, but it might be useful
nevertheless.

DO NOT RUN HUBBOT YOURSELF!  IT ONLY WORKS CORRECTLY IN ITS SPECIAL
ENVIRONMENT ON OUR CI MACHINE.

But you might find the "trigger-hubbot" utility useful.  It can tell
hubbot to work on a pull request, probably to retry a bogus failure.
This could also be used to explicitly white-list pull requests from
external contributors, but that doesn't work yet.

The rest of this README is only about trigger-hubbot.

## Installing

"make install" will copy trigger-hubbot to /usr/local/bin.

## Setup

Put something like this into $HOME/.hubbotrc:

    { 'github_token': "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      'user_whitelist': [],
      'master_repo': "cockpit-project/cockpit",
      'dry_run': False,
      'remote': False,
      'keep_work_dirs': 30
      'os_arch': [{'os': 'fedora-22',
                   'short': 'f22',
                   'arch': 'x86_64',
                   'offset_master': 20,
                   'offset_pull': 20,
                   'publish_images': True
                  },
                  {'os': 'rhel-7',
                   'short': 'r7',
                   'arch': 'x86_64',
                   'offset_master': 20,
                   'offset_pull': 20,
                   'publish_images': False
                  }
                 ],
      'priority_default': 0,
      'priority_needs_attention': -1,
      'priority_work_in_progress': -2,
      'priority_master_changed': 1,
      'priority_essential_failed': 2,
    }

'dry_run' if this is true, no changes are pushed to github.

'remote' specifies if hubbot runs on a remote server. If True, the hubbot.work
files will be looked for via http if they aren't found locally.

'keep_work_dirs' specifies how many output directories will be kept that don't
belong to an open pull request or master. All output directories accessible via
github will be kept in addition to this.

'os_arch' entries:
Of these, 'os' and 'arch' will be used to find the correct images,
whereas the short name is used for status messages.
'offset_master' and 'offset_pull' will be added to priorities with this
configuration.
The first entry is used by default if no configuration is specified
via command line.
If 'publish_images' is set to True, images will be made available for public
download automatically.

Priorities:
By default, all tasks are assigned priority_default.
For pull requests, the github labels and title are considered:
    priority_needs_attention (labels "needsdesign", "needswork")
    priority_work_in_progress (title begins with WIP, case insensitive)
Master is checked daily with the configuration's respective priority.
When checking a pull again because master has changed, its priority is set
to priority_master_changed, ignoring all other modifiers.
If an essential check (base priority >= 20) for a pull request has failed,
other checks for the same pull request will be set to a lower priority:
priority_essential_failed.

The github_token is used to access the GitHub API.  You can create one
for your account at

    https://github.com/settings/applications

When generating a new personal access token, the scope only needs to
encompass public_repo (or repo if you're accessing a private repo).

## Running

To mark pull request number NNN as 'pending', run

    $ trigger-hubbot NNN

This will update the status of the current head commit of the given
pull request in a special way, and hubbot will eventually pick it up
for verification.

If the pull request is target at some other repo than
cockpit-project/cockpit, you can pass it as well:

    $ trigger-hubbot cgwalters/cockpit NNN