scorsh/README.md

scorsh

Signed-Commit Remote Shell

scorsh lets you trigger commands on a remote git server through signed git commits.

scorsh is written in Go.

WTF

...if you have ever felt that git hooks fall too short to your standards...

...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 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 three components:

• the scorsh-commit executable (client-side)

• a post-receive git hook

• 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 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-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-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 -- currently not working)

Build notes

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

In Devuan Jessie unfortunately libgit2 is older than 0.25 so one should first build git2go from its repository, in which libgit2 is a submodule to be built from scratch.

git clone https://github.com/libgit2/git2go
cd git2go
git submodule init
git submodule update
cd libgit2
cmake .
make
sudo make install

Then proceed installing dependencies for scorsh:

make deps

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

scorsh is Copyright (2017) by Vincenzo "KatolaZ" Nicosia.

scorsh is free software. You can use, modify, and redistribute it under the terms of the GNU Affero General Public Licence, version 3 of the Licence or, at your option, any later version. Please see LICENSE.md for details.