Guides

Gitlab pre receive hook

Suggest Edits

Gitlab pre-receive hook

The hook prevents pushing commits with issues that Spectral found.

Prerequisites

  • Gitlab instance on Linux (Windows not supported)
  • Spectral version 1.10.67 and above must be installed on the server: Instructions

Configuration

All configuration is done through a config file.

  1. Create a config file in one of the following directories:
    • .spectral/git-hook directory in your home directory, for example /var/opt/gitlab/.spectral/git-hook/config.yml
    • /etc/spectral/git-hook
  2. Add parameters to config (spectral_dsn and gitlab_host are required):
    # file name for log, must be writable by "git" user
    hook_logfile: /var/log/gitlab/hook.log   # optional, but recommended
    
    # logging level. For debugging purposes level 6 can be used
    log_level: 3    # optional, default is 3 (show errors)
    
    spectral_dsn: https://spk-******@get.spectralops.io   # REQUIRED
    
    # Path to spectral scanner executable. The default is "spectral" 
    # which works if "spectral" binary containing directory is listed in PATH environment variable.
    # It is required to be installed into your gitlab instance. 
    # For installation instructions under your account at get.spectralops.io press "add sources" , then "use CLI",
    # then "local repos".
    spectral_binary: spectral   # optional, default is "spectral"
    
    # Additional arguments to "spectral history" command, for instance, to exclude some checks. Use with caution!
    spectral_args: []   # optional, array of strings
    
    # stop execution after specified number of seconds; child process `spectral` will also be killed
    exec_timeout: 30   # optional, seconds (int), default is 30

    # if this string appears in any of the commit messages being pushed, git hook will skip scanning;
    # use it with caution when you are sure that commits trigger false positive and ONLY false positive scan results;
    # likely, you may want to alter the latest commit message with "amend" commit to skip scanning
    skip_scan_keyword: ~    # string, default "skip-spectral-pre-receive"

    # gitlab server host url
    gitlab_host: http://your-own-gitlab-server.com # REQUIRED
  1. Download the Gitlab pre receive hook.
  2. Install as a server hook, recommended to install globally for all repositories.

Logging

Spectral pre-receive hook allows you to enable the hook logs from the configuration file when the pre-receive hook is triggered.
Before enabling the hook logging, make sure that GitLab logrotate is enabled or custom logrotate that you manage in the server. See gitlab log guide for getting more details.

Spectral pre-receive does not delete or rotate the file that was written in your Gitlab machine.

Enable logging

In the configuration file (config.yaml) change the hook_logfile value to /var/log/gitlab/gitlab-rails (or other path that logrotate is managed and make sure that this path is exists in logrotate.conf file). To get Gitlab logrotate configuration run the following command:

$ cat /var/opt/gitlab/logrotate/logrotate.conf

Chaneg log level

You can always change the log_level value to write more/fewer logs to the file. 3 is the default and indicates an error level, bigger number writes more logging to the file.

Disable logging

log_level field should be empty in the configuration file.

Change Log

V0.0.3

  • Added support for .spectral configuration

V0.0.4

  • Added commits ID to the output
  • Change log level from debug to info
  • Added correlation ID to logs
  • Bugfix - now scanning only pushed commits instead of all branch history

V0.0.5

  • Bugfix - temporary folder is cleaned up in all situations

Updated 3 months ago