Cascading Settings

The cascading settings framework allows groups to essentially inherit settings values from ancestors (parent group on up the group hierarchy) and from instance-level application settings. The framework also allows settings values to be enforced on groups lower in the hierarchy.

Cascading settings can currently only be defined within NamespaceSetting, though the framework may be extended to other objects in the future.

Add a new cascading setting

Settings are not cascading by default. To define a cascading setting, take the following steps:

1. In the NamespaceSetting model, define the new attribute using the cascading_attr helper method. You can use an array to define multiple attributes on a single line.

   class NamespaceSetting
     include CascadingNamespaceSettingAttribute
   
     cascading_attr :delayed_project_removal
   end

2. Create the database columns.

   You can use the following database migration helper for a completely new setting. The helper creates four columns, two each in namespace_settings and application_settings.

   class AddDelayedProjectRemovalCascadingSetting < Gitlab::Database::Migration[2.1]
     include Gitlab::Database::MigrationHelpers::CascadingNamespaceSettings
   
     def up
       add_cascading_namespace_setting :delayed_project_removal, :boolean, default: false, null: false
     end
   
     def down
      remove_cascading_namespace_setting :delayed_project_removal
     end
   end

   Existing settings being converted to a cascading setting will require individual migrations to add columns and change existing columns. Use the specifications below to create migrations as required:

   1. Columns in namespace_settings table:
      • delayed_project_removal: No default value. Null values allowed. Use any column type.
      • lock_delayed_project_removal: Boolean column. Default value is false. Null values not allowed.
   2. Columns in application_settings table:
      • delayed_project_removal: Type matching for the column created in namespace_settings. Set default value as desired. Null values not allowed.
      • lock_delayed_project_removal: Boolean column. Default value is false. Null values not allowed.

Convenience methods

By defining an attribute using the cascading_attr method, a number of convenience methods are automatically defined.

Definition:

cascading_attr :delayed_project_removal

Convenience Methods Available:

• delayed_project_removal
• delayed_project_removal=
• delayed_project_removal_locked?
• delayed_project_removal_locked_by_ancestor?
• delayed_project_removal_locked_by_application_setting?
• delayed_project_removal? (Boolean attributes only)
• delayed_project_removal_locked_ancestor (Returns locked namespace settings object [namespace_id])

Attribute reader method (delayed_project_removal)

The attribute reader method (delayed_project_removal) returns the correct cascaded value using the following criteria:

1. Returns the dirty value, if the attribute has changed. This allows standard Rails validators to be used on the attribute, though nil values must be allowed.
2. Return locked ancestor value.
3. Return locked instance-level application settings value.
4. Return this namespace's attribute, if not nil.
5. Return value from nearest ancestor where value is not nil.
6. Return instance-level application setting.

_locked? method

By default, the _locked? method (delayed_project_removal_locked?) returns true if an ancestor of the group or application setting locks the attribute. It returns false when called from the group that locked the attribute.

When include_self: true is specified, it returns true when called from the group that locked the attribute. This would be relevant, for example, when checking if an attribute is locked from a project.

Display cascading settings on the frontend

There are a few Rails view helpers, HAML partials, and JavaScript functions that can be used to display a cascading setting on the frontend.

Rails view helpers

cascading_namespace_setting_locked?

Calls through to the _locked? method to check if the setting is locked.

HAML partials

_enforcement_checkbox.html.haml

Renders the enforcement checkbox.

_setting_checkbox.html.haml

Renders the label for a checkbox setting.

_setting_label_fieldset.html.haml

Renders the label for a fieldset setting.

_lock_tooltips.html.haml

Renders the mount element needed to initialize the JavaScript used to display the tooltip when hovering over the lock icon. This partial is only needed once per page.

JavaScript

initCascadingSettingsLockTooltips

Initializes the JavaScript needed to display the tooltip when hovering over the lock icon ({lock}). This function should be imported and called in the page-specific JavaScript.

Put it all together

-# app/views/groups/edit.html.haml

= render 'shared/namespaces/cascading_settings/lock_tooltips'

- delayed_project_removal_locked = cascading_namespace_setting_locked?(:delayed_project_removal, @group)
- merge_method_locked = cascading_namespace_setting_locked?(:merge_method, @group)

= form_for @group do |f|
  .form-group{ data: { testid: 'delayed-project-removal-form-group' } }
    = render 'shared/namespaces/cascading_settings/setting_checkbox', attribute: :delayed_project_removal,
        group: @group,
        form: f,
        setting_locked: delayed_project_removal_locked,
        settings_path_helper: -> (locked_ancestor) { edit_group_path(locked_ancestor, anchor: 'js-permissions-settings') },
        help_text: s_('Settings|Projects will be permanently deleted after a 7-day delay. Inherited by subgroups.') do
      = s_('Settings|Enable delayed project deletion')
    = render 'shared/namespaces/cascading_settings/enforcement_checkbox',
        attribute: :delayed_project_removal,
        group: @group,
        form: f,
        setting_locked: delayed_project_removal_locked

  %fieldset.form-group
    = render 'shared/namespaces/cascading_settings/setting_label_fieldset', attribute: :merge_method,
        group: @group,
        setting_locked: merge_method_locked,
        settings_path_helper: -> (locked_ancestor) { edit_group_path(locked_ancestor, anchor: 'js-permissions-settings') },
        help_text: s_('Settings|Determine what happens to the commit history when you merge a merge request.') do
      = s_('Settings|Merge method')

    .gl-form-radio.custom-control.custom-radio
      = f.gitlab_ui_radio_component :merge_method, :merge, s_('Settings|Merge commit'), help_text: s_('Settings|Every merge creates a merge commit.'), radio_options: { disabled: merge_method_locked }

    .gl-form-radio.custom-control.custom-radio
      = f.gitlab_ui_radio_component :merge_method, :rebase_merge, s_('Settings|Merge commit with semi-linear history'), help_text: s_('Settings|Every merge creates a merge commit.'), radio_options: { disabled: merge_method_locked }

    .gl-form-radio.custom-control.custom-radio
      = f.gitlab_ui_radio_component :merge_method, :ff, s_('Settings|Fast-forward merge'), help_text: s_('Settings|No merge commits are created.'), radio_options: { disabled: merge_method_locked }

    = render 'shared/namespaces/cascading_settings/enforcement_checkbox',
      attribute: :merge_method,
      group: @group,
      form: f,
      setting_locked: merge_method_locked

// app/assets/javascripts/pages/groups/edit/index.js

import { initCascadingSettingsLockTooltips } from '~/namespaces/cascading_settings';

initCascadingSettingsLockTooltips();

Vue

cascading_lock_icon.vue

Using Vue

1. In the your Ruby helper, you will need to call the following to send do your Vue component. Be sure to switch out :replace_attribute_here with your cascading attribute.

# Example call from your Ruby helper  method for groups
cascading_settings_data = cascading_namespace_settings_tooltip_data(:replace_attribute_here, @group, method(:edit_group_path))[:tooltip_data]

# Example call from your Ruby helper  method for projects
cascading_settings_data = project_cascading_namespace_settings_tooltip_data(:duo_features_enabled, project, method(:edit_group_path))

1. From your Vue's index.js file, be sure to convert the data into JSON and camel case format. This will make it easier to use in Vue.

let cascadingSettingsDataParsed;
try {
  cascadingSettingsDataParsed = convertObjectPropsToCamelCase(JSON.parse(cascadingSettingsData), {
    deep: true,
  });
} catch {
  cascadingSettingsDataParsed = null;
}

1. From your Vue component, either provide/inject or pass your cascadingSettingsDataParsed variable to the component. You will also want to have a helper method to not show the cascading-lock-icon component if the cascading data returned is either null or an empty object.

// ./ee/my_component.vue

<script>
export default {
  computed: {
    showCascadingIcon() {
      return (
        this.cascadingSettingsData &&
        Object.keys(this.cascadingSettingsData).length
      );
    },
  },
}
</script>

<template>
  <cascading-lock-icon
    v-if="showCascadingIcon"
    :is-locked-by-group-ancestor="cascadingSettingsData.lockedByAncestor"
    :is-locked-by-application-settings="cascadingSettingsData.lockedByApplicationSetting"
    :ancestor-namespace="cascadingSettingsData.ancestorNamespace"
    class="gl-ml-1"
  />
</template>

You can look into the following examples of MRs for implementing cascading_lock_icon.vue into other Vue components:

• Add cascading settings in Groups
• Add cascading settings in Projects

Reasoning for supporing both HAML and Vue

It is the goal to build all new frontend features in Vue and to eventually move away from building features in HAML. However there are still HAML frontend features that utilize cascading settings, so support will remain with initCascadingSettingsLockTooltips until those components have been migrated into Vue.