In this page


This page is about implementing Better Commit Policy specifically in Git repositories managed by the GitLab Self-Managed application. If you use Git, but you don't use GitLab Self-Managed, see the general Git guide instead of this page.

Working with GitLab Self-Managed commit policies

GitLab Self-Managed builds on the top of the Git version control system, extending that with repository-, user- and permission management capabilities. As it is primarily a high-level management layer above Git, everything written in the general Git guide applies to the Git repositories managed by GitLab Self-Managed, too.

In the Better Commit Policy app's context, the only major difference between using Git alone and Git with GitLab Self-Managed is how you install the commit hooks to the central Git repository. (Installing hooks to the local Git repositories is the same for those two cases.)

Installing GitLab Self-Managed hooks

Installing GitLab Self-Managed hooks for remote verification

First, read the GitLab custom hooks page to learn how to install custom hook scripts to GitLab Self-Managed hosted Git repositories in general.

To install the hook script for Better Commit Policy, launch the Hook Script Wizard, select "Git" as VCS, and follow the steps until 1: Unpack the ZIP file to the location where Git expects it. At this step ignore the wizard's instructions, because GitLab is using a slightly different directory structure.

Instead, follow the instructions below:

  1. Locate your Git repository in the server filesystem based on the storage behavior of your GitLab version: We will call this your_repository_dir in the next steps.
  2. Extract the hook script package to a directory named custom_hooks inside your Git repository. If custom_hooks does not exist yet, create it.
  3. Change the owner of the custom_hooks directory and all the files in it to git:git:
    chown -R git:git /var/opt/gitlab/git-data/repositories/your_repository_dir/custom_hooks
  4. Open in a plain text editor, and modify the method called started_manually() at the end of the file to this:
    def started_manually():
    	is_gitlab = "gitlab" in sys.argv[0] and "/custom_hooks/" in sys.argv[0]
    	return not sys.argv[0].startswith("hooks") and not is_gitlab and not sys.argv[0].startswith(".git")
  5. In order to show rejection messages properly in the GitLab web-based file editor, there is one more change to make. Open in a plain text editor and modify the method called print_stderr(*s) to this:
    output_started = False
    def print_stderr(*s):
    	global output_started
    	utf8_supported = not or hook_platform.git()
    	if utf8_supported:
    		encoding = "utf-8"
    		encoding = hook_platform.windows_encoding()
    	for part in s:
    		if not output_started:
    			part = "GL-HOOK-ERR: " + part
    			output_started = True
    		part = part.replace("\n","\nGL-HOOK-ERR: ")
    		if hook_platform.python3():
    			# to print utf-8 correctly, use raw interface for stderr
    			if isinstance(part, str):	# raw interface might need manual encoding
    				part = part.encode(encoding, errors="ignore")
    			if isinstance(part, unicode):
    				part = part.encode(encoding, errors="ignore")
    			print(part, file=sys.stderr, end="")

After this, you can continue executing the steps suggested by the wizard from 2: Set permissions and run a diagnostic test.

When completed, commit policies will be verified both when pushing commits to GitLab Self-Managed and when using the web-based file editor:

Dedicated GitLab extension

Although this solution works perfectly, it could be more convenient. We plan to make the installation process easier by developing a custom GitLab extension.

If you are interested in that, please vote for the feature request by clicking the "thumbs-up" icon. This is very important to get your vote, as we go through the most requested feature requests when planning an upcoming app version.

Also, add a comment with your use case and click "Follow" to be notified when there are updates on that story.

Installing GitLab Self-Managed hooks for local verification

Installing the local hook to a local Git repository which was cloned from a GitLab Self-Managed managed central repository is the same as installing that to any other local Git repository.

See the installing Git hooks for local verification section for detailed instructions.

GitLab Self-Managed commits

In your daily developer workflow, when creating commits and pushing those to GitLab Self-Managed, you can use your Git client exactly the same way as you would with Git alone.

See the Git commits section for detailed instructions.


Ask us any time.