summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md123
1 files changed, 105 insertions, 18 deletions
diff --git a/README.md b/README.md
index e10eae9..83f3386 100644
--- a/README.md
+++ b/README.md
@@ -16,52 +16,56 @@ signed git commits.
...because you would like each specific push event to trigger _something
different_ on the git repo...
-...and you want only authorised users to be able to trigger that
+..and you want only authorised users to be able to trigger that
_something_...
...then **scorsh** might be what you have been looking for.
**scorsh** is a simple system to execute commands on a remote host by
using GPG-signed commits containing customisable commands
-(scorsh-tags). **scorsh** consists of two components:
+(scorsh-tags). **scorsh** consists of three components:
+
+* the `scorsh-commit` executable (client-side)
* a `post-receive` git hook
-* the `scorsh` binary itself
+* the `scorshd` binary itself (server-side)
+
+The `scorsh-commit` executable is used to inject scorsh-commands in a
+regular gpg-signed git commit.
For each new push event, the `post-receive` hook creates a file in a
configurable spool directory, containing information about the repo,
branch, and commits of the push.
-The `scorsh` binary processes inotify events from the spool, parses
+The `scorshd` binary processes inotify events from the spool, parses
each new file there, walks through the new commits looking for signed
ones, checks if the message of a signed commit contains a recognised
-scorsh-tag, verifies that the user who signed the message is allowed
-to use that scorsh-tag, and executes the commands associated to the
-scorsh-tag. Or, well, this is what `scorsh` should be able to do when
-it's finished ;-)
+scorsh-command, verifies that the user who signed the message is
+allowed to use that scorsh-command, and executes the actions
+associated to the scorsh-command.
-The set of scorsh-tags accepted on a repo/branch is configurable, and
-each scorsh-tag can be associated to a list of commands. Commands are
-just URLs, at the moment restricted to two possible types:
+The set of scorsh-commands accepted on a repo/branch is configurable,
+and each scorsh-command can be associated to a list of
+actions. Actions are just URLs, at the moment restricted to two
+possible types:
* `file://path/to/file` - in this case `scorsh` tries to execute the
corresponding file (useful to execute scripts)
* `http://myserver.com/where/you/like` - in this case `scorsh` makes an
HTTP request to the specified URL (useful to trigger other actions,
- e.g., Jenkins or Travis builds...)
+ e.g., Jenkins or Travis builds -- **currently not working**)
-
## Build notes
-**scorsh** depends from the availability of a native build of
-`libgit2` version `0.25` or greater on the native system where
-***scorsh** is built. This dependencies is easily satisfied on various
-operating systems by using their respective package manager. For
-instance in Devuan ASCII one can simply do:
+**scorsh** depends on the availability of a native build of `libgit2`
+version `0.25` or greater on the native system where ***scorsh** is
+built. This dependencies is easily satisfied on various operating
+systems by using their respective package manager. For instance in
+Devuan ASCII one can simply do:
```
sudo apt install libgit2-dev
@@ -92,6 +96,89 @@ And finally build its binary:
make
```
+## Configuration walkthrough (DRAFT)
+
+`scorshd` reads its configuration from a yaml file, normally passed on
+the command line through the option `-c CFG_FILE`. An example is the
+following:
+
+```
+---
+s_spooldir: "./spool"
+s_logfile: "./scorsh.log"
+s_logprefix: "[scorsh]"
+
+s_workers:
+ [
+ {
+ w_name: worker1,
+ w_repos: [".*:.*"], # All branches in all repos
+ w_folder: ./worker1,
+ w_logfile: ./worker1/worker1.log,
+ w_cfgfile: "./worker1/worker1.cfg",
+ },
+ {
+ w_name: worker2,
+ w_repos: [".*:master"], # Branch master in all repos
+ w_folder: ./worker2,
+ w_logfile: ./worker2/worker2.log,
+ w_cfgfile: "./worker2/worker2.cfg",
+ }
+]
+...
+
+```
+
+This files defines two workers. Each worker is associated to a pair of
+`repo:branch` regexps. A worker will be activated only on pushes made
+on a matching `repo:branch`. Each worker has a configuration file
+`w_cfgfile`, where the list of accepted scorsh-commands is
+defined. For instance, for `worker1` we could have:
+
+```
+---
+w_commands:
+ [
+ {
+ c_name: "LOG",
+ c_keyrings: ["allowed_users.asc"],
+ c_actions: [
+ {
+ a_url: "file:///home/katolaz/bin/scorsh_script_log.sh"
+ }
+ ]
+ },
+ {
+ c_name: "build",
+ c_keyrings: ["allowed_users.asc"],
+ c_actions: [
+ {
+ a_url: "file:///home/katolaz/bin/scorsh_script.sh",
+ a_hash: "c129d4a12998c44dfb9a9fd61ec3159bf29606e0f7280f28bbd98fc6f972fa27"
+ }
+ ]
+ },
+ {
+ c_name: "preview",
+ c_keyrings: ["allowed_users.asc"],
+ c_actions: [
+ {
+ a_url: "file:///home/katolaz/bin/scorsh_preview.sh"
+ }
+ ]
+ }
+
+ ]
+...
+```
+
+In this example, `worker1` has three configured scorsh-commands,
+namely `LOG`, `build`, and `preview`. Commands are
+*case-sensitive*. Each command is associated to a list of keyblocks
+(containg the public keys of the users allowed to run that command),
+and to a list of actions.
+
+**TBC**
## License