4:30 p.m.
Repo: git://git.gitano.org.uk/gitano.git
Ref: richardmaw/githookdoc
SHA1: 53db16f34aabc67c67177863c1f3b56c88cca454
This extends the admin manual to contain documentation of how git hooks work.
There is no online documentation of gall's API so it includes a file:// link.
Richard Maw (1):
Add section on git hooks
doc/admin/000.mdwn | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 106 insertions(+)
--
2.9.0
4:30 p.m.
New subject: [PATCH] Add section on git hooks
---
doc/admin/000.mdwn | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 106 insertions(+)
diff --git a/doc/admin/000.mdwn b/doc/admin/000.mdwn
index 770bac8..e41a6e9 100644
--- a/doc/admin/000.mdwn
+++ b/doc/admin/000.mdwn
@@ -433,6 +433,112 @@ so you can split up your rules:
# Branches must not be tags
deny "Branches may only be commits" [ref prefix refs/heads/] [newtype exact
commit]
+# Git Hook scripts
+
+Gitano administrators may create, or delegate creation of
+[Lua][lua] scripts to take action or provide further authentication
+when content is pushed to a repository.
+
+These [Lua][lua] scripts are sandboxed using [Supple][supple],
+to make it safer to run user-defined code.
+
+## How to add a hook
+
+Hooks are stored in the `gitano-admin.git` repository
+and the `refs/gitano-admin` branch of each other repository,
+so that there can be traceability of who is responsible for each hook.
+
+Global hooks in `gitano-admin.git` are loaded
+from the `global-hooks` subdirectory.
+Per-repository hooks in the `refs/gitano-admin` branch
+are loaded from the `hooks` subdirectory.
+
+In both cases hooks are loaded from a file named after the hook
+as defined by [githooks(5)][] suffixed with `.lua`.
+
+Currently the only hooks that are supported are:
+
+1. pre-receive
+2. update
+3. post-receive
+
+So a global pre-receive hook would be in the file `global-hooks/pre-receive.lua`
+and a per-repository post-receive hook would be in `hooks/post-receive.lua`.
+
+## APIs available to hooks
+
+1. `log.$level(...)` to emit text at that log level.
+ $level can be one of:
+
+ 1. `state`
+ 2. `crit` or `critical`
+ 3. `err` or `error`
+ 4. `warn` or `warning`
+ 5. `chat`
+ 6. `info`
+ 7. `debug`
+ 8. `ddebug` or `deepdebug`
+
+2. `fetch(url, headers, body, content_type)` during post-receive hooks.
+
+3. A `repo` object as the first parameter to per-repository hooks,
+ with the following methods:
+
+ ------------------------------------
----------------------------------------------------------------------------
+ `:get(sha1ish)` Get the contents of a git object from anything
matching [gitrevisions(7)][].
+ `:get_config(confname)` Get the value confname from the repo config if
it is a single value
+ `:get_config_list(confname)` Get the value confname from the repo config if
it is a list value
+ `:check_signature(obj, keyringname)` Check whether `obj` is an object signed by a key
in keyring `keyringname`.
+ ------------------------------------
----------------------------------------------------------------------------
+
+ Objects returned from `get` are [gall][] objects.
+ Refer to [gall's API documentation][gall-api] for details.
+
+4. An `info` table as the second parameter to per-repository hook,
+ containing the following indices:
+
+ -------- --------------------------------------------------------------
+ username Gitano username of user doing the push.
+ keytag Name of the ssh key the user is pushing with.
+ source "ssh", "http" or "git" depending on the
protocol used to push.
+ realname Real name of user from user configuration.
+ email E-Mail of user from user configuration.
+ -------- --------------------------------------------------------------
+
+5. The `refname`, `oldsha` and `newsha` as the third to fifth parameters
+ during per-repository update hooks, as described in [githooks(5)][].
+
+ Checking whether the master ref is deleted would be accomplished by:
+
+ local _, _, refname, oldsha, newsha = ...
+ if refname == "refs/heads/master" and newsha == ("0"):rep(40)
then
+ log.state("Master deleted")
+ end
+
+6. For pre-receive or post-receive per-repository hooks as the third parameter,
+ a table indexed by the `refnames` being modified
+ containing tables of the `oldsha` and `newsha` indexed
+ either at positional indices `1` and `2`,
+ or by name `oldsha` and `newsha`.
+ Checking whether the master ref is deleted would be accomplished by:
+
+ local _, _, updates = ...
+ if (updates["refs/heads/master"] or {}).newsha ==
("0"):rep(40) then
+ log.state("Master deleted")
+ end
+
+7. Global hooks work the same as per-repository hooks,
+ except their first parameter is instead a callable function
+ which will run the per-repository hook when called,
+ so global hooks may either replace or augment per-repository hooks.
+
+[lua]: https://www.lua.org/
+[supple]: https://www.gitano.org.uk/supple/
+[githooks(5)]: https://git-scm.com/docs/githooks
+[gitrevisions(7)]: https://git-scm.com/docs/gitrevisions
+[gall]: https://www.gitano.org.uk/gall/
+[gall-api]: file:///usr/share/doc/lua-gall-doc/html/index.html
+
# Backup and restore of a Gitano instance
When gitano-setup is run, the admin needs to specify a Unix user in
--
2.9.0
8:34 p.m.
On Sat, Apr 08, 2017 at 15:30:21 +0100, Richard Maw wrote:
There is no online documentation of gall's API so it includes a
file:// link.
This won't block things, but that's something we should sort as soon as we
have some CI set up.
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
8:51 p.m.
New subject: [PATCH] Add section on git hooks
On Sat, Apr 08, 2017 at 15:30:22 +0100, Richard Maw wrote:
+and the `refs/gitano-admin` branch of each other repository,
that should be `refs/gitano/admin`
+Per-repository hooks in the `refs/gitano-admin` branch
Ditto
+2. `fetch(url, headers, body, content_type)` during post-receive
hooks.
(a) this should be documented further, such as what 'headers' is etc.
(b) while you're right that it's currently only for post-receive, I'd
be interested in knowing if you think we should relax that?
+4. An `info` table as the second parameter to per-repository hook,
+ containing the following indices:
The info table is not passed positionally into the hook functions. It is,
instead passed in a global called 'actor' (see the supple core function in
lib/gitano/supple.lua)
+5. The `refname`, `oldsha` and `newsha` as the third to fifth
parameters
+ during per-repository update hooks, as described in [githooks(5)][].
+
+ Checking whether the master ref is deleted would be accomplished by:
+
+ local _, _, refname, oldsha, newsha = ...
+ if refname == "refs/heads/master" and newsha ==
("0"):rep(40) then
+ log.state("Master deleted")
+ end
I think that'd be local _, refname, oldsha, newsha (as per the above note)
+6. For pre-receive or post-receive per-repository hooks as the
third parameter,
+ a table indexed by the `refnames` being modified
+ containing tables of the `oldsha` and `newsha` indexed
+ either at positional indices `1` and `2`,
+ or by name `oldsha` and `newsha`.
+ Checking whether the master ref is deleted would be accomplished by:
+
+ local _, _, updates = ...
local _, updates = ...
+ if (updates["refs/heads/master"] or {}).newsha ==
("0"):rep(40) then
+ log.state("Master deleted")
+ end
+
+7. Global hooks work the same as per-repository hooks,
+ except their first parameter is instead a callable function
+ which will run the per-repository hook when called,
+ so global hooks may either replace or augment per-repository hooks.
Is it worth showing therefore a passthrough for one of the hooks? E.g.
-- Example global-hooks/update.lua
local hookf, repo, refname, oldsha, newsha = ...
-- Do stuff with repo/refname/oldsha/newsha here
--
-- And finally (optionally) tail-chain through to the per-repo hook
return hookf(repo, refname, oldsha, newsha)
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
8:52 p.m.
On Sat, Apr 08, 2017 at 15:30:21 +0100, Richard Maw wrote:
Repo: git://git.gitano.org.uk/gitano.git
Ref: richardmaw/githookdoc
SHA1: 53db16f34aabc67c67177863c1f3b56c88cca454
Over-all this is good, but it's not quite mergeable as-is.
Please could you fix the typos, and the positional arguments a little.
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
9:32 p.m.
New subject: [PATCH] Add section on git hooks
On Mon, Apr 10, 2017 at 07:51:23PM +0100, Daniel Silverstone wrote:
On Sat, Apr 08, 2017 at 15:30:22 +0100, Richard Maw wrote:
> +and the `refs/gitano-admin` branch of each other repository,
that should be `refs/gitano/admin`
> +Per-repository hooks in the `refs/gitano-admin` branch
Ditto
]:¬( I second-guessed myself about which way around it was
and looked at elsewhere in the document where I had it as refs/gitano-admin,
so it looks like I've got more than 2 places to fix.
> +2. `fetch(url, headers, body, content_type)` during
post-receive hooks.
(a) this should be documented further, such as what 'headers' is etc.
Ok, so headers may be nil or an empty table,
and content_type is separate from headers since it's also optional
so is handy to have special handling positionally,
and the header requires special handling so shouldn't be part of headers.
(b) while you're right that it's currently only for
post-receive, I'd
be interested in knowing if you think we should relax that?
I assumed it was deliberate to dissuade its use for external authentication
by fetching from an external service and failing for taking so long.
> +4. An `info` table as the second parameter to per-repository
hook,
> + containing the following indices:
The info table is not passed positionally into the hook functions. It is,
instead passed in a global called 'actor' (see the supple core function in
lib/gitano/supple.lua)
Bit of a reading comprehension failure there.
> +5. The `refname`, `oldsha` and `newsha` as the third to fifth
parameters
> + during per-repository update hooks, as described in [githooks(5)][].
> +
> + Checking whether the master ref is deleted would be accomplished by:
> +
> + local _, _, refname, oldsha, newsha = ...
> + if refname == "refs/heads/master" and newsha ==
("0"):rep(40) then
> + log.state("Master deleted")
> + end
I think that'd be local _, refname, oldsha, newsha (as per the above note)
Yep.
> +6. For pre-receive or post-receive per-repository hooks as the
third parameter,
> + a table indexed by the `refnames` being modified
> + containing tables of the `oldsha` and `newsha` indexed
> + either at positional indices `1` and `2`,
> + or by name `oldsha` and `newsha`.
> + Checking whether the master ref is deleted would be accomplished by:
> +
> + local _, _, updates = ...
local _, updates = ...
Yep.
> + if (updates["refs/heads/master"] or
{}).newsha == ("0"):rep(40) then
> + log.state("Master deleted")
> + end
> +
> +7. Global hooks work the same as per-repository hooks,
> + except their first parameter is instead a callable function
> + which will run the per-repository hook when called,
> + so global hooks may either replace or augment per-repository hooks.
Is it worth showing therefore a passthrough for one of the hooks? E.g.
-- Example global-hooks/update.lua
local hookf, repo, refname, oldsha, newsha = ...
-- Do stuff with repo/refname/oldsha/newsha here
--
-- And finally (optionally) tail-chain through to the per-repo hook
return hookf(repo, refname, oldsha, newsha)
Potentially.
I think I avoided doing so for the lack of examples
of when you would chain the hooks and when you would override though.
For that matter, if you wanted to provide a default hook
you would have to check whether repo:get("refs/gitano/admin:hooks/$hook.lua")
is a file that exists, since hookf defaults to a no-op callable.
9:38 p.m.
New subject: [PATCH] Add section on git hooks
On Mon, Apr 10, 2017 at 20:32:18 +0100, Richard Maw wrote:
> (b) while you're right that it's currently only for
post-receive, I'd
> be interested in knowing if you think we should relax that?
I assumed it was deliberate to dissuade its use for external authentication
by fetching from an external service and failing for taking so long.
Fair, I couldn't think of the reasoning but this is sound enough for now.
> Is it worth showing therefore a passthrough for one of the
hooks? E.g.
>
> -- Example global-hooks/update.lua
> local hookf, repo, refname, oldsha, newsha = ...
> -- Do stuff with repo/refname/oldsha/newsha here
> --
> -- And finally (optionally) tail-chain through to the per-repo hook
> return hookf(repo, refname, oldsha, newsha)
Potentially.
I think I avoided doing so for the lack of examples
of when you would chain the hooks and when you would override though.
For that matter, if you wanted to provide a default hook
you would have to check whether repo:get("refs/gitano/admin:hooks/$hook.lua")
is a file that exists, since hookf defaults to a no-op callable.
I'm afraid I don't follow. Why would you have to check?
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
9:44 p.m.
New subject: [PATCH] Add section on git hooks
On Mon, Apr 10, 2017 at 08:38:55PM +0100, Daniel Silverstone wrote:
On Mon, Apr 10, 2017 at 20:32:18 +0100, Richard Maw wrote:
> > (b) while you're right that it's currently only for post-receive,
I'd
> > be interested in knowing if you think we should relax that?
>
> I assumed it was deliberate to dissuade its use for external authentication
> by fetching from an external service and failing for taking so long.
Fair, I couldn't think of the reasoning but this is sound enough for now.
To be fair, we don't have a story for external authentication sources,
so perhaps we should experiment with how we _could_ do it that way,
perhaps modify the gitano rulesets to allow by default and check via hook.
That said, I don't think you can change the exit code via hook anyway,
so we can't really do anything about it.
> > Is it worth showing therefore a passthrough for one of the
hooks? E.g.
> >
> > -- Example global-hooks/update.lua
> > local hookf, repo, refname, oldsha, newsha = ...
> > -- Do stuff with repo/refname/oldsha/newsha here
> > --
> > -- And finally (optionally) tail-chain through to the per-repo hook
> > return hookf(repo, refname, oldsha, newsha)
>
> Potentially.
>
> I think I avoided doing so for the lack of examples
> of when you would chain the hooks and when you would override though.
>
> For that matter, if you wanted to provide a default hook
> you would have to check whether
repo:get("refs/gitano/admin:hooks/$hook.lua")
> is a file that exists, since hookf defaults to a no-op callable.
I'm afraid I don't follow. Why would you have to check?
If you're defining a default hook
you should call the local hook if it exists rather than your own hook,
if it doesn't exist you should call your default hook implementation,
but you need to know whether your local hook exists.
From a reading of the code it looks like you never get a nil to say
it's absent
you get a callable that does nothing instead, to make the logic
simpler.
10:17 p.m.
New subject: [PATCH] Add section on git hooks
On Mon, Apr 10, 2017 at 20:44:54 +0100, Richard Maw wrote:
To be fair, we don't have a story for external authentication
sources,
so perhaps we should experiment with how we _could_ do it that way,
perhaps modify the gitano rulesets to allow by default and check via hook.
That said, I don't think you can change the exit code via hook anyway,
so we can't really do anything about it.
You can call fatal() as discussed in person, but it's perhaps a bit of a pig
for this use-case. Let's think 2.x for that :-D>
> I'm afraid I don't follow. Why would you have to
check?
If you're defining a default hook
you should call the local hook if it exists rather than your own hook,
if it doesn't exist you should call your default hook implementation,
but you need to know whether your local hook exists.
Aaah I see, yeah that'd be a pain.
>From a reading of the code it looks like you never get a nil to
say it's absent
you get a callable that does nothing instead, to make the logic simpler.
Indeed. Perhaps I should find a way to signal that to the global hook; but not
for this version. A simple example, and referring to the examples/ tree in the
codebase is likely best for now.
D.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
2435
days inactive
2437
days old
8 comments
2 participants
participants (2)
-
Daniel Silverstone -
Richard Maw