Documented runtime dependencies

2 files changed, 44 insertions, 0 deletions

diff --git a/github/readme.org b/github/readme.org
new file mode 100644
index 0000000..b2e0699
--- /dev/null
+++ b/github/readme.org
@@ -0,0 +1,28 @@
+* GitHub Enterprise Pre-receive Hook Sandbox Environment
+
+GitHub Enterprise imposes certain additional requirements on running
+server-side pre-receive hooks.
+
+1. The hook has a strict 5 second time limit in which to run.
+2. The hook must run within a sandboxed environment, which only lives
+   for the duration of the hook running. The default does not work for
+   Captain Git Hook because it does not include dirmngr.
+
+A suitable sandbox is specified in [[./Dockerfile]]. You can build this
+Dockerfile into an appropriate tarball for upload to GitHub using the
+script [[./create-github-pre-receive-environment.sh]].
+
+#+BEGIN_SRC sh
+  # run this in the same directory as this readme
+  cd github
+
+  # this produces capn-pre-receive.tar.gz
+  ./create-github-pre-receive-environment.sh
+  
+  # you can now upload the tarball to GitHub
+#+END_SRC
+
+The following two documents show how to set up this sandbox
+environment on GitHub:
+- [[https://help.github.com/en/enterprise/2.20/admin/developer-workflow/creating-a-pre-receive-hook-environment]]
+- [[https://help.github.com/en/enterprise/2.20/admin/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance]]
diff --git a/readme.org b/readme.org
index 995d998..4a8dcd1 100644
--- a/readme.org
+++ b/readme.org
@@ -56,6 +56,15 @@ This will add an executable to your path called ~capn~.
 #+END_SRC
 
 ** Usage
+*** Runtime Dependencies
+Captain Git Hook requires certain command line applications to be
+installed and on the path.
+- git - This is used as a binary on the CLI only for cases unsupported
+  by libgit2, such as verifying signatures.
+- gpg - This is used for verifying signatures.
+- dirmngr - This is a gpg component that gpg uses as part of fetching
+  gpg keys from a keyserver. On some distros, this is bundled together
+  with gpg.
 
 *** Git Hooks
 Captain Git Hook works by installing hooks in your Git repository. Git
@@ -76,6 +85,11 @@ How to install this will depend on how you administrate your Git
 server. For example, these are the instructions for GitHub Enterprise:
 [[https://help.github.com/en/enterprise/2.19/admin/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance][Managing pre-receive hooks on the GitHub Enterprise Server appliance]].
 
+Some Git servers, like GitHub Enterprise, require specifying a sandbox
+environment for the pre-receive hook to run in. For convenience, we
+include a Dockerfile and script for setting up a GitHub Enterprise
+sandbox. [[./github/readme.org]]
+
 *** Policy Configuration
 
 The policies that Captain Git Hook will apply for a repo are
@@ -154,6 +168,8 @@ git tag --sign <tag-name>
 git push <remote> <tag-name>
 #+END_SRC
 
+*** Monitoring
+# TODO
 * Development
 ** High level architecture