summaryrefslogtreecommitdiff
path: root/doc/hooks
diff options
context:
space:
mode:
authorDrew Blessing <drew.blessing@me.com>2014-11-07 12:18:00 -0600
committerDrew Blessing <drew.blessing@me.com>2014-11-10 11:01:42 -0600
commit667c0a909bde1cf71f21d8ec9768e98b1c489030 (patch)
tree5ff5180c8c291f67c347a724f2d520a417941e8f /doc/hooks
parent36f9224e4a79b49d0958476395d1472ba9b52a2a (diff)
downloadgitlab-ce-667c0a909bde1cf71f21d8ec9768e98b1c489030.tar.gz
Custom git hook documentation
Diffstat (limited to 'doc/hooks')
-rw-r--r--doc/hooks/custom_hooks.md41
1 files changed, 41 insertions, 0 deletions
diff --git a/doc/hooks/custom_hooks.md b/doc/hooks/custom_hooks.md
new file mode 100644
index 00000000000..00867ead80d
--- /dev/null
+++ b/doc/hooks/custom_hooks.md
@@ -0,0 +1,41 @@
+# Custom Git Hooks
+
+**Note: Custom git hooks must be configured on the filesystem of the GitLab
+server. Only GitLab server administrators will be able to complete these tasks.
+Please explore webhooks as an option if you do not have filesystem access.**
+
+Git natively supports hooks that are executed on different actions.
+Examples of server-side git hooks include pre-receive, post-receive, and update.
+See
+[Git SCM Server-Side Hooks](http://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks)
+for more information about each hook type.
+
+As of gitlab-shell version 2.2.0 (which requires GitLab 7.5+), GitLab
+administrators can add custom git hooks to any GitLab project.
+
+## Setup
+
+Normally, git hooks are placed in the repository or project's `hooks` directory.
+GitLab creates a symlink from each project's `hooks` directory to the
+gitlab-shell `hooks` directory for ease of maintenance between gitlab-shell
+upgrades. As such, custom hooks are implemented a little differently. Behavior
+is exactly the same once the hook is created, though. Follow these steps to
+set up a custom hook.
+
+1. Pick a project that needs a custom git hook.
+1. On the GitLab server, navigate to the project's repository directory.
+For a manual install the path is usually
+`/home/git/repositories/<group>/<project>.git`. For Omnibus installs the path is
+usually `/var/opt/gitlab/git-data/repositories/<group>/<project>.git`.
+1. Create a new directory in this location called `custom_hooks`.
+1. Inside the new `custom_hooks` directory, create a file with a name matching
+the hook type. For a pre-receive hook the file name should be `pre-receive` with
+no extension.
+1. Make the hook file executable and make sure it's owned by git.
+1. Write the code to make the git hook function as expected. Hooks can be
+in any language. Ensure the 'shebang' at the top properly reflects the language
+type. For example, if the script is in Ruby the shebang will probably be
+`#!/usr/bin/env ruby`.
+
+That's it! Assuming the hook code is properly implemented the hook will fire
+as appropriate.