Begiak's git plugin
Begiak has a git plugin that is a post-receive hooks module for the sites it receives commit updates from. The plugin can also provide information about the most recent commits for each repository, and information about individual commits for monitored repositories. The sources for the plugin are in modules/git.py.
Contents
Hook Commands
A post-receive hook is software which performs certain actions on receiving updates about commits from sites like GitHub and Bitbucket. In Begiak's case, Begiak prints out information about commits as they come in to the IRC channels it is present on and notifies administrators. For more about how to set up a webhook, see #Webhook Set-up.
Begiak receives updates from GitHub, Google Code, and Bitbucket. The hook module is started automatically when Begiak is started and connects to an IRC network. All users can check the status of the hook server with
.gitserver status
and administrators can manually start and stop the server with
.gitserver start .gitserver stop
The command `stopserver' is the same as `.gitserver stop'.
Webhook Set-up
A webhook consists of two parts: the service that sends updates and the handler that handles them.
Creating handlers simply involves creating HTTP servers which accept POST requests containing commit information sent by a service. Each POST request usually contains information about the repository, revision number, author, commit message, added/modified/deleted files, etc. For security, a code is provided to authenticate the handler. Additionally, the information is normally sent as JSON data. Each service has slightly different JSON fields in the JSON payload, but it's relatively easy to extract the data.
Begiak implements its handler by deriving it from Python's SimpleHTTPRequestHandler and defining a POST request handler (see the link for documentation). Begiak uses Python's json library to decode the JSON payload it recieves from each service. Begiak is hosted on this server.
Begiak runs at http://apertium.vm.bytemark.co.uk:1234/, so the payload URL/post-commit URL should point there.
However, if you are running locally, Begiak will be running at localhost:1234. Therefore, you would be required to put the payload URL as localhost:1234 in the payload URL box. Since sites such as GitHub cannot see your localhost, you need to use a service such as ngrok in order to expose localhost. Download ngrok here. Once you start a ngrok server using ./ngrok or such, you can place the resulting URL which is found in Forwarding (.ngrok.io format) into the payload URL.
Setting up webhooks on the service's side is very easy with services like GitHub, Google Code, and Bitbucket. How to set up webhooks on these services is explained below:
GitHub
To set up a webhook for a repository on GitHub, navigate to the `Settings -> Webhooks & Service' page. Here, GitHub gives you the option of adding a standard webhook, or adding a service which is a configurable built-in webhook responding to some actions. However, services do not always do what you want and they are, after all, special hooks, so we'll see how to create a webhook.
Once you click on `Add webhook', GitHub may ask you to confirm your password. It then proceeds to the webhook creation page. Firstly, a payload URL must be specified. This is the URL at which the handler is located. Next comes the `Content type': the format in which the content will be sent, either as JSON or as an HTML form with the JSON payload in it. After that, the secret code to authenticate the handler. You then have to select the events which will trigger the hook; events include pull requests being created, commits being made, etc. and are documented in further detail here. Finally, you mark the webhook as being `active' and submit.
Note that for the `Content type' field, there are two options. If the `application/json' option is selected, the JSON data is sent directly as the body of the POST request to the handler; if the `application/x-www-form-urlencoded' option is selected, the JSON data is sent as an HTML form with a field titled `payload' in which the data is actually stored. Begiak's current handlers all use the HTML form option.
Google Code
To set up a webhook for a repository on Google Code, navigate to the `Administer -> Source' tab (you might have to sign in to see it). At the very bottom of the page, there are two fields under the heading of `Post-Commit webhooks': a Post-Commit URL and a Post-Commit Authentication Key, which are the URL at which the handler is located and the authentication code for the handler, respectively. Fill these fields in and save your changes via the button provided; the webhook has been created.
Google Code sends data as JSON. For further documentation on Google Code's webhooks service, see the support page.
Bitbucket
The process of setting up webhooks on Bitbucket is quite well documented on this page.
Adding to Begiak
To add a new service to Begiak or a Begiak fork, or to implement other types of webhooks (i.e. triggered by different events or performing different actions on getting notified of an event), you have to add handling code to the source file modules/git.py, in the `MyHandler' class' `do_POST' method which handles all the POST requests. Code already exists for data decoding; just adding a clause to identify the service/event and then do something with it will suffice.
After the payload URL, you need to add the repo to the config file or in default.py. To add it into the config file you need to do two things: create a dictionary called git_repositories and git_events or add entries if they already exist.
- Create dictionaries, git_repositories and git_events if they do not already exist.
- In the dictionary git_repositories add an entry in the format
"name" : "github_url". Example:git_repositories = {"apertium" : "https://github.com/apertium"} - In the dictionary git_events add an entry in the format
"repository_name" : "[events]". Example:git_events = {'apertium/*': ['issues', 'push']}
git_repositories = {"apertium" : "https://github.com/apertium"}
git_events = {'apertium/*': ['issues', 'push']}
For the events, 'issues' and 'issue_comment', you can add extra actions so that begiak does not spam the channel. 'Action' refers to the specific events, such as the opening of the issue, the editing of a issue_ comment, etc.
issues_x where x is the event that you would like begiak to speak on. The same goes for 'issue_comment'.
You can still get all of the actions if you just type 'issues' or 'issue_comment'.
Examples:
- Only opened actions for 'issues' => 'issues_opened'.
- Only created actions for 'issue_comment' => issue_comment_created'.
- All actions for 'issue_comment' => issue_comment'.
- All actions for 'issues' => 'issues'.
Recent Commits
Begiak can get information for the most recent commits for the repositories it monitors. The command
begiak: recent OR begiak, recent
will print the commit reports.
This command currently does not work.
Commit Information
Begiak can get commit information for a specified repository and revision. The command
begiak: info <repo> <rev> OR begiak, info <repo> <rev>
will print the commit report. Note that this module does not try to handle SVN repositories (they are handled by modules/svnpoller.py) and other repositories it does not monitor.
This command currently does not work.
