1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
# scorsh
**Signed-Commit Remote Shell**
**scorsh** lets you trigger commands on a remote **git** server through commits, optionally signed with **gnupg**.
**scorsh** is written in Go.
## Why scorsh
...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 git commits containing customisable commands
(scorsh-tags) that can be authenticated using a gnupg signature . **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.26` 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 most distributions unfortunately `libgit2` is older than `0.26` so
one should first build this exact release version from source,
available
here:
[https://github.com/libgit2/libgit2/releases/tag/v0.26.0](libgit2 release 0.26)
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.
|
