Add readme and sample config

README.md

@@ -0,0 +1,75 @@
+# `bebot`
+
+Bebot is a Gitlab webhook handler that publishes messages to Matrix when
+interesting things happen in your configured repos.
+
+Currently-supported Gitlab event types:
+
+* Push events
+* Tag push events
+* Issue events
+* Merge request events
+* Pipeline events (only publishes on failure for now)
+
+## Building
+
+Bebot is written in Rust, and requires a Rust toolchain in order to
+build.  The usual `cargo build` or `cargo build --release` will do the
+trick.
+
+You can also build and install the latest released version of Bebot by
+running `cargo install bebot`.
+
+## Setup
+
+Bebot requires a configuration file in YAML format.  See
+`sample-config.yaml` for all existing configuration options.  They
+should hopefully be fairly self-explanatory, but a few clarifications:
+
+1. `bind_address` and `bind_port` determine what IP/interface and port
+   the webhook handler will listen on.
+2. Bebot's webhook will be served from `/hooks/gitlab`.  You can use
+   `url_prefix` to prepend further path segments in front of that.
+3. `user_id` and `password` are for the Matrix user that the bot will
+   sign into Matrix as.  Ensure that `user_id` is the full username,
+   including the homeserver.
+4. `default_room` is the room that Bebot will publish to if not
+   specified in the per-repo configuration.
+5. `repo_configs` is a map where the key is of the form
+   `$GITLAB_INSTANCE/$NAMESPACE/$REPO`.  It is recommended that you use
+   a unique, randomly-generated `token` for each repository.  You can
+   specify `room` here as well if you don't want messages to go to
+   `default_room`.
+
+When setting up the webhook in Gitlab, use the same `token` from the
+configuration file in the webhook's "Secret token" field.  You should
+only select "Push events", "Tag push events", "Issues events", "Merge
+request events", and "Pipeline events".  You can leave some of these out
+if you don't want Bebot to publish messages for everything.
+
+Bebot does not support serving the webhook over TLS, so you will
+probably want to put it behind a reverse-proxy such as nginx.
+
+In the `scripts` directory is a `set-webhook.py` script that can set up
+(or update) webhooks for your repository, automatically generating a
+token for you.  If setting up the webhook for the first time, it will
+output to stdout a YAML snippet that goes under the `repo_configs`
+section of the configuration file.  If you run the script with no
+arguments, it will print out usage details.
+
+## Running
+
+After you've done all that, simply run Bebot:
+
+```
+bebot /path/to/config-file.yaml
+```
+
+You can set the `BEBOT_LOG` environment variable to increase or decrease
+logging verbosity.  (Try `debug`, `info`, `warn` `error`, or `off`.)
+
+### Docker
+
+A `Dockerfile` is also provided.  When running the container it builds,
+mount the configuration file so it appears inside the container as
+`/bebot/config/bebot.yaml`.

sample-config.yaml

@@ -0,0 +1,12 @@
+bind_address: 127.0.0.1
+bind_port: 3000
+url_prefix: "/bebot"
+user_id: "@mybebot:example.com"
+password: "secret-matrix-account-password"
+default_room: "#my-project-commits:example.com"
+repo_configs:
+  "gitlab.example.com/myorg/my-cool-app":
+    token: "abcdefg12345"
+  "gitlab.example.com/myuser/some-other-less-cool-app":
+    room: "#my-other-room:example.com"
+    token: "kljaslkdjaklsdjalksd"