diff --git a/README.adoc b/README.adoc index cd35931..a827473 100644 --- a/README.adoc +++ b/README.adoc @@ -1 +1,91 @@ = Git Webhook Client + +Git webhook client that runs commands after a webhook event and shows their output. + +Currently, only Gitea is supported. If you want support for Gitlab or Github, then please open an issue. + +== Features + +* Verify the webhook event with a secret. +* Run a configured command to a specific repository on a webhook event. +* Save the output of the command. +* Show an output by visiting the url of the client. +* Supported configuration for multiple repositories. +* Written in Rust :D + +== Getting started + +=== Requirements + +* `cargo` to compile the source code. +* Development package for SQLite (`sqlite-devel` on Fedora) + +=== Configuration + +The program looks for the configuration file `config.json` that contains the following: + +. `secret`: The secret of the webhook. +. `base_url`: The base_url of the webhook client. +. `hooks`: List of webhooks. +.. `repo_url`: Repository url. +.. `current_dir`: The directory to run the command in. +.. `command`: The command without any arguments. +.. `args`: List of arguments separated by a comma. + +==== Example configuration file: + +[source, json] +---- +{ + "secret": "CHANGE_ME!", + "base_url": "https://webhook.mo8it.xyz", + "hooks": [ + { + "repo_url": "https://codeberg.org/Mo8it/git-webhook-client", + "current_dir": ".", + "command": "ls", + "args": ["-l", "-a", "test_directory"] + } + ] +} +---- + +==== First setup + +* Clone the repository. +* Create the configuration file. +* Run the following to initialize the database: +. +[source, bash] +---- +cargo install diesel_cli --no-default-features --features sqlite +DATABASE_URL=PATH/TO/DATABASE/DIRECTORY/db.sqlite diesel_cli migration run +cargo build --release +---- + +==== Run + +After running `cargo build --release`, the binary can be found in the directory `target/release/git-webhook-client`. To run it, you have to specify the environment variable `DATABASE_URL`: + +[source, bash] +---- +DATABASE_URL=PATH/TO/DATABASE/DIRECTORY/db.sqlite target/release/git-webhook-client +---- + +==== Setup on the git server + +Setup the webhook for the configured repositories on the git server. Don't forget to enter the same secret that you did specify in the configuration file. + +==== Show output + +After an event, the client responds with a URL that shows the log. The id in that URL is important and specific to this event. + +If you want to see the last log, just visit the `base_url` from the configuration. + +To see a specific log with an id, visit the URL: `base_url/?id=THE_ID_OF_AN_EVENT`. + +You can specify a negative ID to see the last events. `id=-1` corresponds to the last log, `id=-2` corresponds to the log before it and so on. + +== Note + +This is my first Rust project and I am still learning. If you have any suggestions, just open an issue!