Gerrit Module

Overview
Module Description - What the module does and why it is useful
Setup - The basics of getting started with gerrit
- What gerrit affects
- Setup requirements
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

Overview

This module installs and configures a Gerrit system. It is intended to work with Puppet >= v3.7, =< v.4.2.3 as that is what it is developed against. For newer puppet versions there is no complete rspec tests coverage for now but it may still work.

Module Description

The Gerrit module provides an easy way of standing up a Gerrit server, an open source web based code review system.

The optional MySQL integration works with the puppetlabs-mysql module to export a database configuration for automatic pick-up and creation of the database. The module does not presently probe to see if the database has been created as this is not a feature of the puppetlabs-mysql module like it is in the puppetlabs-postgresql module. As such, if the exported DB has not been picked up yet this module will fail to initialize Gerrit until the database is available.

The module may optionally modify the firewall for the web and ssh services.

You may optionally manage your Gerrit site Header, Footer and CSS as well as the static resources.

You may optionally install and configure the plugins that ship with Gerrit. The default is to install the full list of plugins that v2.9.3 shipped. One of these plugins (replication) requires a separate config file, no default configuration file is created so the plugin will load and then do nothing until a configuration file is managed in and the plugin is either restarted or the Gerrit service is restarted.

Setup

What gerrit affects

The gerrit service will be installed and managed
May optionally install java (NOTE: java is required for Gerrit to work)
May optionally install git (NOTE: git is required for Gerrit to work)
Gerrit site Header, Footer and CSS may be optionally managed. If they are not managed then dummy files will be put in place (also optional) so that adding managed files later will not require a restart.
May optionally install gitweb
May optionally manage the firewall rules for access to Gerrit resources
May optionally handle setting up the database (potential cross-system dependencies)
May optionally acquire and install 3rd party plugins

Setup Requirements

puppetlabs/git is required for the optional git installation. If you wish to manage git via a different module / method make sure to set $manage_git to false
puppetlabs/java >= v1.2.0 is required for the optional java installation. If you wish to use manage java via a different module / method make sure to set $manage_java to false
puppetlabs/mysql >= 3.0.0 is required for the optional MySQL management as well as having store configs enabled.
puppetlabs/firewall >= 1.2.0 is required for the optional firewall management
maestrodev/wget >= 1.5.7 is required for optional 3rd party plugin installation if a http or https url is provided for the plugin source

Usage

This module is designed to do automatic hiera lookups a fairly common setup might look like the following. A note about the database password, if you feel uncomfortable about having your passwords in the clear in your hiera, it is recommendend that you look into hiera-eyaml and hiera-eyaml-gpg

---

# The DB tag that will be used to pickup our MySQL export
gerrit::db_tag: 'myenv-db'

# Use a version newer than the default of 2.9.3
gerrit::version: '2.11'

# Manage a replication.config
gerrit::extra_configs:
  replication_config:
    config_file: '/opt/gerrit/etc/replication.config'
    mode: '0644'
    options:
      'remote.github':
        url: '[email protected]:exampleco/${name}.git'
        push:
          - '+refs/heads/*:refs/heads/*'
          - '+refs/tags/*:refs/tags/*'
        timeout: '5'
        threads: '5'
        authGroup: 'GitHub Replication'
        remoteNameStyle: 'dash'

# Manage the gerrit system itself
gerrit::override_options:
  auth:
    type: 'OPENID'
  cache:
    directory: 'cache'
  database:
    type: 'MYSQL'
    hostname: 'mysql.exampleco.com'
    database: 'gerrit'
    username: 'gerrit'
  gerrit:
    basePath: '/srv/gerrit'
    canonicalWebUrl: 'https://gerrit.exampleco.com/r'
  gitweb:
    cgi: '/var/www/git/gitweb.cgi'
  httpd:
    listenUrl: 'proxy-https://*:8080/r'
  sendemail:
    smtpServer: 'localhost'
    from: 'ExampleCo Code Review <[email protected]>'
  sshd:
    listenAddress: '*:29418'
  user:
    email: '[email protected]'
  commentlink.bugzilla:
    match: '([Bb][Uu][Gg]\\s*[:-]?\\s*)(\\d+)'
    link: 'https://bugs.exampleco.com/show_bug.cgi?id=$2'

gerrit::override_secure_options:
  database:
    password: 'My$up3r@wes0mePASSw0rd'

include ::gerrit

Reference

`db_tag`

The tag to be used by exported database resource records so that a collecting system may easily pick up the database resource

`download_location`

Base location for downloading the Gerrit war from. Defaults to the official Gerrit download location

`extra_configs`

A hash that is used to add additional configuration files to the Gerrit system. The hash is a hash of hashes where the top level keys are the resource identifier for a configuration file and each config_file option is the fully qualified filename that should be written out.

The hash is formatted as follows:

extra_configs               => {
  configID1                 => {
    config_file             => 'fully_qualified_file_name',
    mode                    => '0644',
    options                 => {
      'section1'            => {
        'option1'           => 'basic string option',
        'option2'           => [
          'option2 array entry 1',
          'option2 array entry 2'
        ],
      },
      'section2.subsection' => {
        'option3' => 'option 3 in [section2 "subsection"]'
      },
    },
  },
  configID2                 => {
    config_file             => 'another_fully_qualified_file_name',
    mode                    => '0644',
    options                 => {
      'section1'            => {
        'option1'           => 'one more option string',
      },
    }
  }
}

This is most useful when managing the replication.config file for the replication plugin a hiera config would look something like this:

gerrit::extra_configs:
  replication_config:
    config_file: '/opt/gerrit/etc/replication.config'
    mode: '0644'
    options:
      'remote.github':
        url: '[email protected]:exampleco/${name}.git'
        push:
          - '+refs/heads/*:refs/heads/*'
          - '+refs/tags/*:refs/tags/*'
        timeout: '5'
        threads: '5'
        authGroup: 'GitHub Replication'
        remoteNameStyle: 'dash'

`gerrit_group`

The primary group of the gerrit user. Default value: gerrit

`gerrit_home`

The home directory for the gerrit user / installation path. Default value: /opt/gerrit

`gerrit_site_options`

Override options for installation of the 3 Gerrit site files. The format of this option hash is as follows:

gerrit_site_options       => {
  'GerritSite.css'        => 'a valid file resource source',
  'GerritSiteHeader.html' => 'a valid file resource source',
  'GerritSiteFooter.html' => 'a valid file resource source',
}

If an option is not present then the default "blank" file will be used.

This hash is only used if manage_site_skin is true (default)

`gerrit_user`

The user that Gerrit runs as. Default gerrit

`gerrit_version`

The version of the Gerrit war that will be downloaded. Default 2.9.3

`gitweb_package_name`

The name of the package to install for gitweb should install_gitweb be true. Defaults to gitweb

`install_default_plugins`

Should the default plugins be installed? If true (default) then use the plugin_list array to specify which plugins specifically should be installed.

`install_git`

Should this module make sure that git is installed? (NOTE: a git installation is required for Gerrit to be able to operate. If this is true (default) then a module named ::git will be included. puppetlabs/git is the expected module but any module that can be blindly included and use APL to configure it that matches on the include will work.)

`install_gitweb`

Should this module make sure that gitweb is installed? (NOTE: This will use the system package manager to install gitweb but will do no extra configuration as it will be expected to be managed via gerrit)

`install_java`

Should this module make sure that a JRE is installed? (NOTE: a JRE installation is required for Gerrit to operate. If this is true (default) then a module named ::java will be included. puppetlabs/java is the expected module but any module that can be blindly included and use APL to configure it that matches on the include will work.)

`manage_database`

Should the database be managed. The default option of true means that if a MySQL or PostgresQL database is detected in the options then resources will be exporte via the puppetlabs/{mysql/postgresql} module API. A db_tag (see above) needs to be set as well so that a system picking up the resource can acquire the appropriate exported resources.

NOTE: PostgreSQL resource exports do not presently work.

`manage_firewall`

Should the module insert firewall rules for the webUI and SSH? Default setting: true

NOTE: This requires a module compatible with the puppetlabs/firewall API

`manage_site_skin`

Should the Gerrit site theming be managed by the module? If true (default) then passing an options hash to gerrit_site_options (see above) will override the default "blank" skin files that get pushed.

`manage_static_site`

Should the ~gerrit/static structure be managed by the module? Default setting: false

If true then static_source (see below) is required.

`manage_user`

Should this module create the gerrit_user and gerrit_group (true) or will they be managed elsewhere (false)? Default setting: true

`override_options`

A variable hash for configuration settings of Gerrit. These options are mreged into the default option define and then written to ~gerrit/etc/gerrit.config. The default Gerrit options are as follows:

default_options => {
  'auth'        => {
    'type'      => 'OpenID',
  },
  'container'   => {
    'javaHome'  => '/usr/lib/jvm/jre',
  },
  'gerrit'      => {
    'basePath'  => '/srv/gerrit',
  },
  'index'       => {
    'type'      => 'LUCENE',
  },
}

`override_secure_options`

Similar to override_options, this hash is used for setting the options in the ~gerrit/etc/secure.config file. The defult secure options are as follows:

default_secure_options        => {
  'auth'                      => {
    'registerEmailPrivateKey' => 'GENERATE',
    'restTokenPrivateKey'     => 'GENERATE',
  },
}

The special GENERATE keywords will be replaced by host fqdn stable random strings. The option is only valid on the two default keys and will not operate on any other keys passed in. This is done to mimic a manual installation as those strings are generated normally for you.

They may, of course, be overriden by this override hash.

`plugin_list`

An array specifying the default plugins that should be installed. The names are specified without the .jar. The current plugins auto-installed are the ones that ship with v2.9.3 the list is as follows:

plugin_list => [
  'commit-message-length-validator',
  'download-commands',
  'replication',
  'reviewnotes'
]

`refresh_service`

Should the gerrit service be refreshed on modifications to either the gerrit.config or sercure.config? Default: true

`service_enabled`

Determines the mode that the service is configured for:

true: (default) service is ensured started and enabled for reboot

false: service is ensured stopped and disabled for reboot

manual: service is configured as a manual service, refreshes will behave per normal when a service is configured with enable => manual. The service is not specified specifically started or stopped.

`static_source`

A File resource source that will be recursively pushed if manage_static_site is set to true. All files in the source will be pushed to the ~gerrit/site.

`third_party_plugins`

A hash declaring all the third party plugins that should be installed. The sources may be file, puppet or http(s) sources.

If http or https resources are defined thanmaestrodev/wget is needed for fetching the resources.

The hash looks like the following:

third_party_plugins => {
  'delete-project'  => {
    plugin_source   =>
    'https://gerrit-ci.gerritforge.com/view/Plugins-stable-2.11/job/plugin-delete-project-stable-2.11/lastSuccessfulBuild/artifact/buck-out/gen/plugins/delete-project/delete-project.jar',
  },
}

Limitations

Tested against RedHat / CentOS v7

Name		Name	Last commit message	Last commit date
Latest commit History 106 Commits
files/skin		files/skin
manifests		manifests
spec		spec
templates		templates
tests		tests
.fixtures.yml		.fixtures.yml
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
Gemfile		Gemfile
README.md		README.md
Rakefile		Rakefile
metadata.json		metadata.json

tykeal/puppet-gerrit

Folders and files

Latest commit

History

Repository files navigation

Gerrit Module

Table of Contents

Overview

Module Description

Setup

What gerrit affects

Setup Requirements

Usage

Reference

db_tag

download_location

extra_configs

gerrit_group

gerrit_home

gerrit_site_options

gerrit_user

gerrit_version

gitweb_package_name

install_default_plugins

install_git

install_gitweb

install_java

manage_database

manage_firewall

manage_site_skin

manage_static_site

manage_user

override_options

override_secure_options

plugin_list

refresh_service

service_enabled

static_source

third_party_plugins