Upgrading to new major versions¶

Some of these changes between major application versions may affect the effective configuration that would be applied if you run the application. Therefore to do the upgrade safely please follow this procedure.

From 4.* to 5.*¶

Update `config_version`¶

Update config_version to 4. Then update configuration syntax as described in following sections.

Remove deprecated MR approval config¶

GitLabForm v5 removed configuration syntax for merge request approval settings that were deprecated in v3. In addition, following config will not be processed anymore.

config_version: 4

projects_and_groups:
  group_1/project_1:
    merge_requests:
      approvals:
        approvals_before_merge: 2
        reset_approvals_on_push: true
        disable_overriding_approvers_per_merge_request: true
      approvers:
        - user1
        - user2
      approver_groups:
        - my-group
        - my-group1/subgroup
        - my-group2/subgroup/subsubgroup
      remove_other_approval_rules: false

New config syntax supported as of GitLabForm v3.4.0:

config_version: 4

projects_and_groups:
  group_1/project_1:
    merge_requests_approvals:
      disable_overriding_approvers_per_merge_request: true
    merge_requests_approval_rules:
      any: # this is just a label
        approvals_required: 0
        name: "Any member"
        rule_type: any_approver
      enforce: true

Update config syntax for group saml links¶

In previous versions of GitLabForm, saml links at a group level were under saml_group_links. This key has been renamed to group_saml_links to be consistent with other group level configuration syntax.

projects_and_groups:
  group_1/*:
    saml-group-links:
    group_saml_links: 
      devops_are_maintainers: # this is just a label
        saml_group_name: devops
        access_level: maintainer

Branch Protection Changes¶

In GitLabForm v4, branch protection config introduced a bug. GitLabForm would remove and re-add branch protection on every run, because GitLab's API did not support in-place updates. Besides causing audit noise because of constant change, this approach reset all unspecified attributes to GitLab defaults, breaking GitLabForm’s core behavior of raw parameter passing — where only explicitly configured values are sent, and unspecified ones are left untouched.

This unintended consequence meant:

A user configuring only some protection attributes (e.g. push_access_level) would find others reset to default (e.g. code_owner_approval_required) on re-run.
GitLabForm was no longer idempotent unless all settings were always provided.

This issue is being fixed by following original intended behaviour of GitLabForm. Therefore, if you wish to ensure the Protected Branch settings are applied as you intend when running GitlabForm you should define some defaults explicitly:

projects_and_groups:
 my-group/*:
   branches:
     main:
       protected: true
       allow_force_push: false
       code_owner_approval_required: true

Protected key is Mandatory¶

The documentation has always mandated that the protected key must be present in GitlabForm configuration, set to either true or false.

From v5 GitlabForm will exit Fatally if there is a branch under branches configuration without the protected key, for example the following will now error fatally:

projects_and_groups:
 my-group/*:
   branches:
     main:
       # This configuration is now invalid due to lacking the `protected` flag and will cause GitlabForm to fail
       allow_force_push: false
       code_owner_approval_required: true
     my_other_protected_branch:
       # Valid configuration
       protected: true

From 3.* to 4.*¶

Relatively minor breaking-change, we dropped support for Python < 3.12, so if you are running locally using Python rather than Docker, ensure you are using Python > 3.12

From 2.* to 3.*¶

Steps outline:

Update to the latest v2.x.x and fix all the deprecation warnings the application prints out during run. The syntax deprecated in v2 has been removed in v3.
Stop v2 from running automatically (if you have such automation).
In your config:
- In v3 a bug that caused subgroup config to not inherit its group config has been fixed. If you do have configs for some groups and a config for their subgroups, then your effective configuration may change after the upgrade to v3. If you do not want that, or you are not sure, then please do the following to keep the old behavior: add inherit: false entries to all of such subgroups config, under each configuration section: Example:
```
projects_and_groups:
  some_group/*:
    group_settings:
      project_creation_level: maintainer
      subgroup_creation_level: owner
      visibility: internal

  some_group/subgroup/*:
    group_settings:
      # add the line below to keep the old behavior
      inherit: false
      project_creation_level: developer

  some_group/subgroup/subsubgroup/*:
    group_settings:
      # add the line below to keep the old behavior
      inherit: false
      visibility: private
```
- Replace services: with integrations:,
- Replace secret_variables: with variables:,
- Replace group_secret_variables: with group_variables:,
- Replace config_version: 2 with config_version: 3
- Update merge_requests:; approvals_before_merge: needs to be defined in specific approval rule
Upgrade the app from v2 to v3.
Re-enable v3 to run automatically (if you have such automation).

From 1.* to 2.*¶