145 lines
3.5 KiB
Markdown
145 lines
3.5 KiB
Markdown
# GitHub Webhook Handler
|
|
|
|
## Simple C++ WebAPI to work with GitHub Webhooks
|
|
|
|
This application is a simple C++ WebAPI that listens for GitHub Webhooks and performs actions based on the received data and configuration.
|
|
|
|
## Installation
|
|
|
|
### Use installation script (recommended)
|
|
|
|
Run the installation script to install the application:
|
|
|
|
```console
|
|
curl -fsSL https://cdn.tiagorg.pt/gh-wh-handler/install.sh | sudo sh
|
|
```
|
|
|
|
You can uninstall the application using the following command:
|
|
|
|
```console
|
|
curl -fsSL https://cdn.tiagorg.pt/gh-wh-handler/uninstall.sh | sudo sh
|
|
```
|
|
|
|
### Run prebuilt binary
|
|
|
|
Head over to the [Releases Page](https://github.com/TiagoRG/gh-wh-handler/releases) and download the desired binary.
|
|
|
|
Run the application using your configuration file:
|
|
```console
|
|
/path/to/gh-wh-handler.<arch> /path/to/config.json /path/to/logs_dir
|
|
```
|
|
|
|
You can see the config file format below.
|
|
|
|
### Install from source
|
|
|
|
#### Install the dependencies:
|
|
|
|
- [CrowCpp](https://crowcpp.org/master/)
|
|
- [nlohmann::json](https://github.com/nlohmann/json)
|
|
|
|
#### Build and install the application:
|
|
|
|
1. Clone the repository:
|
|
|
|
```console
|
|
git clone https://github.com/TiagoRG/gh-wh-handler.git
|
|
```
|
|
|
|
2. Move to the build directory:
|
|
```console
|
|
cd gh-wh-handler/build
|
|
```
|
|
|
|
3. Run CMake:
|
|
```console
|
|
cmake ..
|
|
```
|
|
|
|
4. Build and install the application:
|
|
```console
|
|
sudo make install
|
|
```
|
|
|
|
If you want to uninstall the application, you can run the following command:
|
|
```console
|
|
sudo make uninstall
|
|
```
|
|
|
|
## Usage
|
|
|
|
The application is running on a systemd service, which is both enabled and started after installation.
|
|
|
|
You can start, stop, restart, and check the status of the service using the following commands:
|
|
|
|
```console
|
|
sudo systemctl start gh-wh-handler # Start the service
|
|
sudo systemctl stop gh-wh-handler # Stop the service
|
|
sudo systemctl restart gh-wh-handler # Restart the service
|
|
sudo systemctl status gh-wh-handler # Check the status of the service
|
|
```
|
|
|
|
You can also check the logs of the service using the following command:
|
|
|
|
```console
|
|
journalctl -u gh-wh-handler
|
|
```
|
|
|
|
## Configuration
|
|
|
|
As of now, the configuration menu is not yet implemented so you have to create the configuration file manually.
|
|
|
|
### Config File
|
|
|
|
The configuration file can be found in `/services/gh-wh-handler/config.json` and has the following base format:
|
|
|
|
```json
|
|
{
|
|
"port": 65001,
|
|
"tokens": {
|
|
"owner/repo-name": "token"
|
|
}
|
|
}
|
|
```
|
|
|
|
This configuration will then have more fields for each endpoint that you want to configure.
|
|
|
|
Note: Tokens are only required for private repositories.
|
|
|
|
## Endpoints
|
|
|
|
Currently, the only endpoint for the application is `/update-files`, which is used to update the local files on every push as well as run post-update scripts.
|
|
|
|
### `/update-files`
|
|
|
|
#### Webhook event: `push`
|
|
|
|
This endpoint allows the application to update specific files on the server when a push to a specific branch is made. This way, there's no need to manually update the files on the server or to pull the entire repository.
|
|
|
|
It also allows the application to run post-update scripts after the files are updated.
|
|
|
|
The configuration file must contain the `update-files` field, which is an object with the following format:
|
|
|
|
```json
|
|
"update-files": {
|
|
"owner/repo-name": {
|
|
"branch": "main",
|
|
"files": {
|
|
"path/to/remote/file": "/path/to/local/file",
|
|
"...": "..."
|
|
},
|
|
"post-update": [
|
|
"post-update-command",
|
|
"post-update-script",
|
|
"..."
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
|
|
|
|
|