Difference between revisions of "Begiak's git plugin"
(Document creation of webhooks) |
(Document webhook set-up) |
||
| Line 6: | Line 6: | ||
== |
== Hook Commands == |
||
A post-receive hook is |
A post-receive hook is software which performs certain actions on |
||
receiving updates about commits from sites like GitHub and |
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 |
Begiak's case, Begiak prints out information about commits as they come in to |
||
the IRC channels it is present on and notifies administrators. |
the IRC channels it is present on and notifies administrators. For more about how to set up a webhook, see [[#Webhook Set-up]]. |
||
A webhook consists of two parts: the service that sends updates and the hook that handles them. Many services are now offering the option to enable webhooks, and you can configure them to send updates to your hook handler(s). Creating handlers is also very easy, as they are simply 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. which can all be retrieved using a secret code that the service provides. Begiak implements its handler by deriving it from Python's |
|||
[https://docs.python.org/3/library/http.server.html#http.server.SimpleHTTPRequestHandler SimpleHTTPRequestHandler] |
|||
and defining its POST handler to get the data. |
|||
Begiak receives updates from GitHub, Google Code, and Bitbucket. The hook module |
Begiak receives updates from GitHub, Google Code, and Bitbucket. The hook module |
||
| Line 25: | Line 21: | ||
.gitserver stop |
.gitserver stop |
||
The command `stopserver' is the same as `.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 |
|||
[https://docs.python.org/3/library/http.server.html#http.server.SimpleHTTPRequestHandler SimpleHTTPRequestHandler] and defining a POST request handler (see the link for documentation). Begiak uses Python's [https://docs.python.org/3/library/json.html json] library to decode the JSON payload it recieves from each service. Begiak is hosted on [http://apertium.vm.bytemark.co.uk this server]. |
|||
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 [https://developer.github.com/webhooks here]. Finally, you mark the webhook as being `active' and submit. |
|||
=== 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 [http://code.google.com/p/support/wiki/PostCommitWebHooks the support page]. |
|||
=== Bitbucket === |
|||
The process of setting up webhooks on Bitbucket is quite well documented [https://confluence.atlassian.com/display/BITBUCKET/Manage+Bitbucket+hooks on this page]. |
|||
Revision as of 09:54, 4 January 2015
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.
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.
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.
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.
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.
