feature/package_hold

* Introducing the `package_hold`parameter

The `package_hold` parameter allows you to hold the package version in the APT
package manager. This is useful when you intend to update the host with
'apt upgrade' (or the bolt task `apt action=upgrade` from puppetlabs-apt) and
keep your gitlab instance at the intended version. This prevents unintended
upgrading gitlab and perhaps skipping important upgrade path steps.

README.md

@@ -222,7 +222,7 @@ Each unique resource provided to the `repository_configuration` setup:
 
 You can use these tags to further customize ordering within your own catalogs.
 
-#### Selecting Version, edition, and package name
+#### Selecting Version, edition, package name and holding
 
 The `package_ensure` parameter is used to control which version of the package
 installed. It expects either a version string, or one of the `ensure` values for
@@ -242,6 +242,13 @@ This approach of package management has the following advantages:
 * allows you to install custom built packages for gitlab-omnibus that have
   different package name on your host
 
+The `package_hold` parameter allows you to hold the package version in the APT
+package manager. This is useful when you intend to update the host with
+'apt upgrade' (or the bolt task `apt action=upgrade` from puppetlabs-apt) and
+keep your gitlab instance at the intended version. This prevents unintended
+upgrading gitlab and perhaps skipping important upgrade path steps.
+To learn more about gitlab upgrading please visit the [upgrade path page.](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/)
+
 #### Custom Repository & Package configuration example
 
 As an expanded example of repository and package configuration, let's assume you're:

REFERENCE.md

@@ -121,6 +121,7 @@ The following parameters are available in the `gitlab` class:
 * [`backup_cron_minute`](#-gitlab--backup_cron_minute)
 * [`backup_cron_hour`](#-gitlab--backup_cron_hour)
 * [`backup_cron_skips`](#-gitlab--backup_cron_skips)
+* [`package_hold`](#-gitlab--package_hold)
 * [`package_name`](#-gitlab--package_name)
 * [`manage_package`](#-gitlab--manage_package)
 * [`repository_configuration`](#-gitlab--repository_configuration)
@@ -825,6 +826,18 @@ Array of items to skip valid values: db, uploads, repositories, builds, artifact
 
 Default value: `[]`
 
+##### <a name="-gitlab--package_hold"></a>`package_hold`
+
+Data type: `Enum['hold', 'none']`
+
+Allows you to hold the specific package version as installed currently on your
+system. Useful when you intent to upgrade your system without accidentally
+upgrading gitlab without it's proper upgrade path.
+It is recommended to use this parameter together with the `package_ensure`
+parameter.
+
+Default value: `none`
+
 ##### <a name="-gitlab--package_name"></a>`package_name`
 
 Data type: `Optional[String]`
@@ -1028,6 +1041,7 @@ This class is called from gitlab for install.
 The following parameters are available in the `gitlab::install` class:
 
 * [`package_name`](#-gitlab--install--package_name)
+* [`package_hold`](#-gitlab--install--package_hold)
 * [`package_ensure`](#-gitlab--install--package_ensure)
 * [`manage_package`](#-gitlab--install--manage_package)
 
@@ -1039,6 +1053,14 @@ Data type: `Any`
 
 Default value: `$gitlab::package_name`
 
+##### <a name="-gitlab--install--package_hold"></a>`package_hold`
+
+Data type: `Any`
+
+
+
+Default value: `$gitlab::package_hold`
+
 ##### <a name="-gitlab--install--package_ensure"></a>`package_ensure`
 
 Data type: `Any`

manifests/init.pp

@@ -86,6 +86,7 @@
 # @param backup_cron_minute The minute when to run the daily backup cron job
 # @param backup_cron_hour The hour when to run the daily backup cron job
 # @param backup_cron_skips Array of items to skip valid values: db, uploads, repositories, builds, artifacts, lfs, registry, pages
+# @param package_hold Wether to hold the specified package version. Available options are 'hold' or 'none'. Defaults to 'none'. Available only for Debian/Solaris package managers. 
 # @param package_name The internal packaging system's name for the package. This name will automatically be changed by the gitlab::edition parameter. Can be overridden for the purposes of installing custom compiled version of gitlab-omnibus.
 # @param manage_package Should the GitLab package be managed?
 # @param repository_configuration A hash of repository types and attributes for configuraiton the gitlab package repositories. See docs in README.md
@@ -158,6 +159,7 @@
   Optional[Hash]                      $pgbouncer_exporter              = undef,
   Optional[Hash]                      $gitlab_monitor                  = undef,
   Optional[Hash]                      $gitlab_exporter                 = undef,
+  Enum['hold', 'none']                $package_hold                    = 'none',
   Optional[String]                    $package_name                    = undef,
   Optional[String]                    $pages_external_url              = undef,
   Optional[Hash]                      $pages_nginx                     = undef,

manifests/install.pp

@@ -2,6 +2,7 @@
 class gitlab::install (
   $package_name   = $gitlab::package_name,
   $package_ensure = $gitlab::package_ensure,
+  $package_hold   = $gitlab::package_hold,
   $manage_package = $gitlab::manage_package,
 ) {
   assert_private()
@@ -26,6 +27,7 @@
     package { 'gitlab-omnibus':
       ensure  => $package_ensure,
       name    => $_package_name,
+      mark    => $package_hold,
       require => Class['gitlab::omnibus_package_repository'],
     }
   }