2021-04-22 18:10:13 +00:00
---
stage: Manage
group: Access
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Cascading Settings
> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/321724).
2021-04-23 03:09:40 +00:00
The cascading settings framework allows groups to essentially inherit settings
values from ancestors (parent group on up the group hierarchy) and from
2021-04-22 18:10:13 +00:00
instance-level application settings. The framework also allows settings values
2021-04-23 03:09:40 +00:00
to be enforced on groups lower in the hierarchy.
2021-04-22 18:10:13 +00:00
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.
2021-04-23 03:09:40 +00:00
2021-04-22 18:10:13 +00:00
```ruby
class NamespaceSetting
include CascadingNamespaceSettingAttribute
cascading_attr :delayed_project_removal
end
```
1. Create the database columns.
2021-04-23 03:09:40 +00:00
You can use the following database migration helper for a completely new setting.
The helper creates four columns, two each in `namespace_settings` and
2021-04-22 18:10:13 +00:00
`application_settings` .
2021-04-23 03:09:40 +00:00
2021-04-22 18:10:13 +00:00
```ruby
class AddDelayedProjectRemovalCascadingSetting < ActiveRecord::Migration [ 6 . 0 ]
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
```
2021-04-23 03:09:40 +00:00
2021-04-22 18:10:13 +00:00
Existing settings being converted to a cascading setting will require individual
2021-04-23 03:09:40 +00:00
migrations to add columns and change existing columns. Use the specifications
below to create migrations as required:
2021-04-22 18:10:13 +00:00
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.
1. Columns in `application_settings` table:
2021-04-23 03:09:40 +00:00
- `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.
2021-04-22 18:10:13 +00:00
## Convenience methods
By defining an attribute using the `cascading_attr` method, a number of convenience
2021-04-23 03:09:40 +00:00
methods are automatically defined.
2021-04-22 18:10:13 +00:00
**Definition:**
```ruby
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])
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
2021-04-23 03:09:40 +00:00
Rails validators to be used on the attribute, though `nil` values *must* be allowed.
2021-04-22 18:10:13 +00:00
1. Return locked ancestor value.
1. Return locked instance-level application settings value.
1. Return this namespace's attribute, if not nil.
1. Return value from nearest ancestor where value is not nil.
1. Return instance-level application setting.