GitHub Webhook server. Listens for updates from GitHub for projects, and runs update scripts against the changes.
The primary goal of this project is to provide a simple continuous integration/delivery platform for GitHub projects. For example, koukku can be used for deploying the latest version of a website which has source code hosted at GitHub.
- Koukku listens for updates from GitHub by providing a webhook access.
- It triggers an update for a received event, if a match is found in configuration.
- It updates the matching project's local repository with changes from remote repository.
- It runs user configured update script in the local repository directory.
You can install koukku using Rust's Cargo:
$ cargo install koukku
USAGE:
koukku [FLAGS] --config <FILE>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-c, --config <FILE> Configuration file location
The configuration follows the INI-format. The top level keys contain common configurations, and the sections contain project specific configurations. Here's an example configuration:
location = /path/to/projects
gitpath = /usr/bin/git
server = 0.0.0.0:3000
threads = 2
[myproject]
repo = githubname/myrepo
key = foobar
branch = master
command = /path/to/somescript.sh
Project repositories should be placed to where location points to.
The repositories in this directory are identified using the section ID.
For example, in the above configuration example the project would be found from
/path/to/projects/myproject.
| Key | Description |
|---|---|
| server | Server address to run on. Default: localhost:8888 |
| threads | Number of threads to run the web server on. Default: relative to cores |
| location | The directory where repositories are located |
| gitpath | Path to git binary. Default: /usr/bin/git |
| Key | Description |
|---|---|
| repo | GitHub repository in format username/repository |
| key | Webhook secret key |
| branch | Git branch to track. Default: master |
| command | The command to run on webhook trigger |
See GitHub's Creating Webhooks guide. Currently, koukku only supports JSON payloads.
Koukku uses Rust's log and env_logger for logging.
Change the RUST_LOG environment to tune logging.
Recommended setup:
RUST_LOG="error,koukku=info"
Here's an example unit file for running koukku using systemd:
[Unit]
Description=Github Webhook service
After=network.target
[Service]
ExecStart=/path/to/koukku --config /path/to/conf.ini
WorkingDirectory=/path/to/workingdir
User=koukku
Group=koukku
PIDFile=/path/to/koukku.pid
Environment=RUST_LOG=error,koukku=info
[Install]
WantedBy=default.target
Change the paths, the user, and the group accordingly, and place the file to /etc/systemd/system/koukku.service.
See to systemd documentation for more information.
For running koukku, you need to install OpenSSL libraries.
See rust-openssl and your operating system's guides for more information.
For building koukku, you need to install Rust compiler and tools.
Use Rust's cargo to build the project:
$ cargo build
The build will create a debug executable into path target/debug/koukku.
You can create an optimized executable using --release flag.
$ cargo build --release
The executable can be found from path target/release/koukku.
You can also run the executable directly using cargo run:
$ cargo run -- --config myconf.ini --server localhost:3030
Tests can be run using cargo test:
$ cargo test
See Cargo guide for more information on using Cargo.
(MIT License)
Copyright (c) 2016 Jaakko Pallari
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.