gitlabform 6.2.4__tar.gz → 6.3.0__tar.gz

{gitlabform-6.2.4 → gitlabform-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitlabform
-Version: 6.2.4
+Version: 6.3.0
 Summary: 🏗 Specialized configuration as a code tool for GitLab projects, groups and more using hierarchical configuration written in YAML
 Project-URL: Homepage, https://gitlabform.github.io/gitlabform/
 Project-URL: Repository, https://github.com/gitlabform/gitlabform.git
@@ -23,10 +23,10 @@ Requires-Dist: certifi==2026.7.22
 Requires-Dist: cli-ui==0.19.0
 Requires-Dist: jinja2==3.1.6
 Requires-Dist: luddite==1.0.4
-Requires-Dist: markupsafe==3.0.3
+Requires-Dist: markupsafe==3.0.4
 Requires-Dist: mergedeep==1.3.4
 Requires-Dist: packaging==26.3
-Requires-Dist: python-gitlab[graphql]==8.5.0
+Requires-Dist: python-gitlab[graphql]==8.6.0
 Requires-Dist: requests==2.34.2
 Requires-Dist: rich==15.0.0
 Requires-Dist: ruamel-yaml==0.19.1

{gitlabform-6.2.4 → gitlabform-6.3.0}/docs/changelog.md

@@ -6,6 +6,23 @@ For details on how to migrate between major versions, please refer to the [upgra
 
 ---
 
+## 6.3.0
+
+### Features
+
+* show diff in dry-run mode for group settings [#1462](https://github.com/gitlabform/gitlabform/pull/1462). ([vetlekise](https://github.com/vetlekise))
+* skip branch protection for non-existent branches [#1457](https://github.com/gitlabform/gitlabform/pull/1457). ([amimas](https://github.com/amimas))
+
+### Refactors
+
+* migrate protected environments processor to python-gitlab [#1438](https://github.com/gitlabform/gitlabform/pull/1438). ([rickbrouwer](https://github.com/rickbrouwer))
+
+### Dependencies
+
+* Update various dependencies to newer versions.
+
+Thanks to all the contributors of this release!
+
 ## 6.2.4
 
 ### Performance

{gitlabform-6.2.4 → gitlabform-6.3.0}/docs/contrib/implementation_design.md

@@ -100,7 +100,7 @@ Sometimes there is some logic in these methods if:
 * we only need a specific part of the response from GitLab API - see `GitLabProjects.get_all_projects()` as an example,
 * some GitLab APIs need some workarounds for their bugs or documentation inconsistencies, like:
     * some APIs declare in the docs that they accept both "group/project" string OR a project id while in fact only the latter works - see `GitLabProjects.post_approvals()` as an example,
-    * some APIs return invalid HTTP error codes, like 404 instead of 400 - see `GitLabGroupLDAPLinks.add_ldap_group_link` as an example.
+    * some APIs return invalid HTTP error codes, like 404 instead of 400 - see `GroupLDAPLinksProcessor._create_link` as an example.
 
 **Note**: Some of the code here is **NOT used by the GitLabForm app**, but utilized by internal Egnyte
 applications that have not (yet) switched to the more standard `python-gitlab`.

{gitlabform-6.2.4 → gitlabform-6.3.0}/docs/reference/protected_branches.md

@@ -105,6 +105,38 @@ projects_and_groups:
         allow_force_push: true
 ```
 
+### Project only option
+
+This option is only supported for project-level branch protection under `branches`, and is a GitLabForm-specific feature.
+
+GitLab allows creating branch protection even when a branch does not exist. This is useful so that a branch is automatically protected when it matches the configured name. If this is not desired, use a top-level key named `skip_missing_branch: true`. Setting this flag will skip branch protection for a branch when it does not exist.
+
+This is intended for exact branch names only. It does not apply to wildcard patterns such as `release-*`.
+
+- If `strict` mode is enabled, GitLabForm still fails on missing literal branches.
+- If `strict` mode is disabled, GitLabForm skips protecting a missing literal branch and continues.
+
+Example:
+
+```yaml
+projects_and_groups:
+  group_1/project_1:
+    branches:
+      skip_missing_branch: true
+      main:
+        protected: true
+        push_access_level: no access
+        merge_access_level: maintainer
+      branch-that-does-not-exist-yet:  # This will be skipped
+        protected: true
+        push_access_level: no access
+        merge_access_level: maintainer
+      "release-*":
+        protected: true
+        push_access_level: no access
+        merge_access_level: maintainer
+```
+
 ### Premium-only features
 
 !!! info

{gitlabform-6.2.4 → gitlabform-6.3.0}/gitlabform/__init__.py

@@ -56,6 +56,7 @@ class GitLabForm:
         noop=False,
         output_file=None,
         recurse_subgroups=True,
+        strict=True,
     ):
         if target and config_string:
             # this mode is basically only for testing
@@ -64,7 +65,7 @@ class GitLabForm:
             self.config_string = config_string
             self.verbose = True
             self.debug = True
-            self.strict = True
+            self.strict = strict
             self.start_from = 1
             self.start_from_group = 1
             self.noop = noop

{gitlabform-6.2.4 → gitlabform-6.3.0}/gitlabform/gitlab/__init__.py

@@ -10,9 +10,7 @@ from gitlabform.gitlab.commits import GitLabCommits
 from gitlabform.gitlab.groups import GitLabGroups
 from gitlabform.gitlab.merge_requests import GitLabMergeRequests
 from gitlabform.gitlab.pipelines import GitLabPipelines
-from gitlabform.gitlab.project_protected_environments import (
-    GitLabProjectProtectedEnvironments,
-)
+from gitlabform.gitlab.projects import GitLabProjects
 from gitlabform.gitlab.project_merge_requests_approvals import (
     GitLabProjectMergeRequestsApprovals,
 )
@@ -46,12 +44,13 @@ class AccessLevel(enum.IntEnum):
         return [level.name.lower().replace("_", " ") for level in AccessLevel]
 
 
+# GitLabGroups and GitLabProjects stay as bases until gitlabform/lists/ no longer uses their methods
 class GitLab(
     GitLabCommits,
     GitLabGroups,
     GitLabMergeRequests,
     GitLabPipelines,
-    GitLabProjectProtectedEnvironments,
+    GitLabProjects,
     GitLabProjectMergeRequestsApprovals,
 ):
     pass

{gitlabform-6.2.4 → gitlabform-6.3.0}/gitlabform/processors/group/group_settings_processor.py

@@ -11,6 +11,9 @@ class GroupSettingsProcessor(AbstractProcessor):
     def __init__(self, gitlab: GitLab):
         super().__init__("group_settings", gitlab)
 
+    def _get_current_state(self, group: str) -> dict:
+        return self.gl.get_group_by_path_cached(group).asdict()
+
     def _process_configuration(self, group: str, configuration: Dict):
         configured_group_settings = configuration.get("group_settings", {})
 

{gitlabform-6.2.4 → gitlabform-6.3.0}/gitlabform/processors/project/__init__.py

@@ -36,7 +36,7 @@ from gitlabform.processors.project.resource_groups_processor import (
 from gitlabform.processors.project.schedules_processor import SchedulesProcessor
 from gitlabform.processors.project.tags_processor import TagsProcessor
 from gitlabform.processors.project.project_variables_processor import ProjectVariablesProcessor
-from gitlabform.processors.shared.protected_environments_processor import (
+from gitlabform.processors.project.protected_environments_processor import (
     ProtectedEnvironmentsProcessor,
 )
 

{gitlabform-6.2.4 → gitlabform-6.3.0}/gitlabform/processors/project/branches_processor.py

@@ -39,8 +39,11 @@ class BranchesProcessor(AbstractProcessor):
         self.custom_diff_analyzers["unprotect_access_levels"] = BranchProtection.naive_access_level_diff_analyzer
 
     def _can_proceed(self, project_or_group: str, configuration: dict):
-        for branch in sorted(configuration["branches"]):
-            branch_config = configuration["branches"][branch]
+        branches_config = dict(configuration.get("branches", {}))
+        branches_config.pop("skip_missing_branch", None)
+
+        for branch in sorted(branches_config):
+            branch_config = branches_config[branch]
             if branch_config.get("protected") is None:
                 critical(f"The Protected key is mandatory in branches configuration, fix {branch} YAML config")
                 sys.exit(EXIT_INVALID_INPUT)
@@ -54,36 +57,51 @@ class BranchesProcessor(AbstractProcessor):
         """
 
         project: Project = self.gl.get_project_by_path_cached(project_and_group)
+        branches_config: dict = dict(configuration["branches"])
+        skip_missing_branch_enabled: bool = branches_config.pop("skip_missing_branch", False)
 
-        for branch in sorted(configuration["branches"]):
-            branch_configuration: dict = self.convert_user_and_group_names_to_ids(configuration["branches"][branch])
-
-            self.process_branch_protection(project, branch, branch_configuration)
+        for branch in sorted(branches_config):
+            self.process_branch_protection(project, branch, branches_config[branch], skip_missing_branch_enabled)
 
-    def process_branch_protection(self, project: Project, branch_name: str, branch_config: dict):
+    def process_branch_protection(
+        self, project: Project, branch_name: str, branch_configuration: dict, skip_if_missing: bool
+    ):
         """
         High-level logic for processing branch protection.
 
         1. Validates branch existence (unless wildcard).
         2. Handles 'protected: false' (unprotecting).
         3. Handles 'protected: true':
-           - If not currently protected: Create protection.
-           - If protected: Update using PATCH (EE > 15.6) or Unprotect/Reprotect (CE/Old EE).
+            - If not currently protected: Create protection.
+            - If protected: Update using PATCH (EE > 15.6) or Unprotect/Reprotect (CE/Old EE).
+        4. Skips protection if the branch does not exist and 'skip_if_missing' is enabled.
+            - This is only applicable for literal branch names, not wildcards.
         """
         protected_branch: Optional[ProjectProtectedBranch] = None
 
         # If protected branch name contains a supported wildcard do not try looking it up
         if not self.branch_name_contains_supported_wildcard(branch_name):
-            # Check branch we are trying to protect actually exists first
+            # Check branch we are trying to protect actually exists first.
+            # When explicitly requested, skip missing literal branches instead of creating
+            # a protection rule for a branch that does not exist yet.
             try:
                 project.branches.get(branch_name)
-            except GitlabGetError:
+            except GitlabGetError as e:
+                if e.response_code != 404:
+                    raise
+
                 message = f"Branch '{branch_name}' not found when processing it to be protected/unprotected!"
                 if self.strict:
                     critical(message)
                     sys.exit(EXIT_INVALID_INPUT)
                 else:
                     warning(message)
+                    if skip_if_missing:
+                        info(
+                            f"Skipping branch protection for '{branch_name}' because the branch does not exist and "
+                            "skip_missing_branch is enabled."
+                        )
+                        return
 
         try:
             protected_branch = project.protectedbranches.get(branch_name)
@@ -91,6 +109,8 @@ class BranchesProcessor(AbstractProcessor):
             message = f"The branch '{branch_name}' is not protected!"
             info(message)
 
+        branch_config: dict = self.convert_user_and_group_names_to_ids(branch_configuration)
+
         if branch_config.get("protected"):
             if not protected_branch:
                 info(f"Creating branch protection for {branch_name}")

gitlabform-6.3.0/gitlabform/processors/project/protected_environments_processor.py

@@ -0,0 +1,68 @@
+from logging import info
+from typing import Dict, List
+
+from gitlab.v4.objects import Project, ProjectProtectedEnvironment
+
+from gitlabform.gitlab import GitLab
+from gitlabform.processors.abstract_processor import AbstractProcessor
+
+
+class ProtectedEnvironmentsProcessor(AbstractProcessor):
+    def __init__(self, gitlab: GitLab):
+        super().__init__("protected_environments", gitlab)
+        # deploy_access_levels is a list of dicts; compare positionally, ignoring keys
+        # that GitLab adds (id, description) but the config doesn't set.
+        self.custom_diff_analyzers["deploy_access_levels"] = self.recursive_diff_analyzer
+
+    def _process_configuration(self, project_and_group: str, configuration: Dict):
+        # copy, so that popping "enforce" does not mutate the shared configuration,
+        # which is reused when this method is retried
+        configured_envs: Dict = dict(configuration.get("protected_environments", {}))
+        enforce = configured_envs.pop("enforce", False)
+
+        project: Project = self.gl.get_project_by_path_cached(project_and_group)
+        existing_envs: List[ProjectProtectedEnvironment] = project.protected_environments.list(get_all=True)
+
+        processed_names: set = set()
+
+        for entity_name, env_config in configured_envs.items():
+            name = env_config["name"]
+            matching = next((env for env in existing_envs if env.name == name), None)
+
+            if env_config.get("delete", False):
+                if matching:
+                    info(f"Deleting {entity_name} of {self.configuration_name} in {project_and_group}")
+                    matching.delete()
+                else:
+                    info(
+                        f"Not deleting {entity_name} of {self.configuration_name} in {project_and_group},"
+                        f" because it doesn't exist"
+                    )
+                processed_names.add(name)
+                continue
+
+            if matching:
+                if self._needs_update(matching.asdict(), env_config):
+                    # The API has an update endpoint (https://docs.gitlab.com/api/protected_environments/),
+                    # but python-gitlab's ProjectProtectedEnvironmentManager doesn't support it, so we recreate.
+                    info(f" * Recreating {entity_name} of {self.configuration_name} in {project_and_group}")
+                    matching.delete()
+                    project.protected_environments.create(env_config)
+                else:
+                    info(
+                        f" * {entity_name} of {self.configuration_name} in {project_and_group}"
+                        f" doesn't need an update."
+                    )
+            else:
+                info(f" * Adding {entity_name} of {self.configuration_name} in {project_and_group}")
+                project.protected_environments.create(env_config)
+            processed_names.add(name)
+
+        if enforce:
+            for existing in existing_envs:
+                if existing.name not in processed_names:
+                    info(
+                        f"Deleting protected environment '{existing.name}' of {self.configuration_name}"
+                        f" in {project_and_group} as it's not in config and enforce is set to true."
+                    )
+                    existing.delete()

{gitlabform-6.2.4 → gitlabform-6.3.0}/pyproject.toml

@@ -10,7 +10,7 @@ packages = ["gitlabform"]
 
 [project]
 name = "gitlabform"
-version = "6.2.4"
+version = "6.3.0"
 requires-python = ">=3.12.0"
 authors = [{ name = "Greg Dubicki and Contributors" }]
 description = "🏗 Specialized configuration as a code tool for GitLab projects, groups and more using hierarchical configuration written in YAML"
@@ -35,10 +35,10 @@ dependencies = [
     "cli-ui==0.19.0",
     "jinja2==3.1.6",
     "luddite==1.0.4",
-    "markupsafe==3.0.3",
+    "markupsafe==3.0.4",
     "mergedeep==1.3.4",
     "packaging==26.3",
-    "python-gitlab[graphql]==8.5.0",
+    "python-gitlab[graphql]==8.6.0",
     "requests==2.34.2",
     "rich==15.0.0",
     "ruamel.yaml==0.19.1",
@@ -53,16 +53,16 @@ dev = [
     { include-group = "lint" },
     { include-group = "docs" },
     { include-group = "release" },
-    "commitizen==4.18.0",
-    "prek==0.5.2",
+    "commitizen==4.18.1",
+    "prek==0.5.3",
 ]
 # Minimum set of dependencies required to execute the test suite.
 test = [
-    "coverage==7.16.0",
+    "coverage==7.16.1",
     "cryptography==50.0.1",
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
-    "pytest-rerunfailures==16.6.1",
+    "pytest-rerunfailures==16.7",
     "xkcdpass==1.30.0",
 ]
 # Static analysis and formatting tools.
@@ -72,15 +72,15 @@ lint = [
     "codespell==2.4.3",
     "mypy==2.3.1",
     "mypy-extensions==1.1.0",
-    "ruff==0.16.5",
-    "types-requests==2.33.0.20260712",
+    "ruff==0.16.8",
+    "types-requests==2.33.0.20260906",
 ]
 # Documentation generation stack.
 docs = [
     "markdown==3.10.3",
-    "zensical==0.0.58",
+    "zensical==0.0.62",
     "pygments==2.21.0",
-    "pymdown-extensions==11.0.2",
+    "pymdown-extensions==12.0.1",
 ]
 # Tools required for building and verifying releases.
 release = [

{gitlabform-6.2.4 → gitlabform-6.3.0}/tbump.toml

@@ -2,7 +2,7 @@
 github_url = "https://github.com/gitlabform/gitlabform/"
 
 [version]
-current = "6.2.4"
+current = "6.3.0"
 
 # Example of a semver regexp.
 # Make sure this matches current_version before

{gitlabform-6.2.4 → gitlabform-6.3.0}/tests/acceptance/__init__.py

@@ -338,6 +338,7 @@ def run_gitlabform(
     noop: bool = False,
     output_file: Optional[str] = None,
     recurse_subgroups: bool = True,
+    strict: bool = True,
 ) -> None:
     """
     Runs GitLabForm with the given configuration and target.
@@ -362,5 +363,6 @@ def run_gitlabform(
         noop=noop,
         output_file=output_file,
         recurse_subgroups=recurse_subgroups,
+        strict=strict,
     )
     gf.run()

{gitlabform-6.2.4 → gitlabform-6.3.0}/tests/acceptance/standard/test_branches.py

@@ -452,3 +452,62 @@ class TestBranches:
 
         ### Check branch_for_function is not protected
         assert project_for_function.branches.get(branch_for_function).protected is False
+
+    def test__skip_missing_literal_branch_but_keep_wildcard_behavior(
+        self, project_for_function, branch_for_function, is_enterprise_edition
+    ):
+        project = project_for_function
+        branch = branch_for_function
+        missing_branch_name = get_random_name("missing-")
+        wildcard_branch = "skip-*"
+
+        config_protect_branches = f"""
+        projects_and_groups:
+          {project.path_with_namespace}:
+            branches:
+              skip_missing_branch: true
+              {branch}:
+                protected: true
+                push_access_level: {AccessLevel.NO_ACCESS.value}
+                merge_access_level: {AccessLevel.MAINTAINER.value}
+                unprotect_access_level: {AccessLevel.MAINTAINER.value}
+              "{missing_branch_name}":
+                protected: true
+                push_access_level: {AccessLevel.NO_ACCESS.value}
+                merge_access_level: {AccessLevel.MAINTAINER.value}
+                unprotect_access_level: {AccessLevel.MAINTAINER.value}
+              "{wildcard_branch}":
+                protected: true
+                push_access_level: {AccessLevel.NO_ACCESS.value}
+                merge_access_level: {AccessLevel.MAINTAINER.value}
+                unprotect_access_level: {AccessLevel.MAINTAINER.value}
+        """
+
+        # Run gitlabform with strict mode enabled, which should raise an error due to the missing branch
+        with pytest.raises(SystemExit) as exc_info:
+            run_gitlabform(config_protect_branches, project.path_with_namespace, strict=True)
+        assert exc_info.value.code == 1
+
+        # Run gitlabform with strict mode disabled, which should skip the missing branch and continue processing
+        run_gitlabform(config_protect_branches, project.path_with_namespace, strict=False)
+
+        protected_branches = {pb.name for pb in project.protectedbranches.list()}
+        assert branch in protected_branches
+        assert missing_branch_name not in protected_branches
+
+        wildcard_matching_branch = project.branches.create({"branch": "skip-1", "ref": "main"})
+        assert wildcard_matching_branch.protected is True
+
+        if is_enterprise_edition:
+            (
+                _,
+                _,
+                _,
+                _,
+                _,
+                _,
+                unprotect_access_level,
+            ) = get_only_branch_access_levels(project, branch)
+            assert unprotect_access_level is AccessLevel.MAINTAINER.value
+        else:
+            assert True

{gitlabform-6.2.4 → gitlabform-6.3.0}/tests/acceptance/standard/test_group_settings.py

@@ -1,3 +1,5 @@
+import logging
+
 from tests.acceptance import run_gitlabform
 
 
@@ -31,3 +33,24 @@ class TestGroupSettings:
 
         group = gl.groups.get(group.id)
         assert group.path == current_value
+
+    def test__dry_run_shows_diff_and_does_not_edit(self, gl, group_for_function, caplog):
+        group = group_for_function
+        original_description = group.description
+        assert original_description != "foobar"
+
+        edit_group_settings = f"""
+        projects_and_groups:
+          {group.full_path}/*:
+            group_settings:
+              description: foobar
+        """
+
+        with caplog.at_level(logging.INFO):
+            run_gitlabform(edit_group_settings, group, noop=True)
+
+        assert "group_settings changes" in caplog.text
+        assert "foobar" in caplog.text
+
+        group = gl.groups.get(group.id)
+        assert group.description == original_description

{gitlabform-6.2.4 → gitlabform-6.3.0}/tests/unit/processors/test_branches_processor.py

@@ -1,5 +1,7 @@
 from unittest.mock import MagicMock
 
+from gitlab import GitlabGetError
+
 from gitlabform.gitlab import AccessLevel
 from gitlabform.processors.project.branches_processor import BranchesProcessor
 from gitlabform.processors.util.branch_protection import BranchProtection
@@ -27,6 +29,36 @@ class TestBranchesProcessor:
         assert BranchesProcessor.branch_name_contains_supported_wildcard("main") is False
         assert BranchesProcessor.branch_name_contains_supported_wildcard("feature-123") is False
 
+    def test_skip_missing_branch_skips_protection_for_missing_literal_branch_from_global_branches_config(self):
+        project = MagicMock()
+        project.branches.get.side_effect = GitlabGetError("not found", 404)
+        project.protectedbranches.get.side_effect = GitlabGetError("not protected", 404)
+
+        self.processor.gl = MagicMock()
+        self.processor.gl.get_project_by_path_cached.return_value = project
+
+        self.processor._process_configuration(
+            "group/project",
+            {"branches": {"skip_missing_branch": True, "main": {"protected": True}}},
+        )
+
+        project.protectedbranches.create.assert_not_called()
+
+    def test_skip_missing_branch_does_not_skip_wildcard_branch_protection(self):
+        project = MagicMock()
+        project.branches.get.side_effect = GitlabGetError("not found", 404)
+        project.protectedbranches.get.side_effect = GitlabGetError("not protected", 404)
+
+        self.processor.gl = MagicMock()
+        self.processor.gl.get_project_by_path_cached.return_value = project
+
+        self.processor._process_configuration(
+            "group/project",
+            {"branches": {"skip_missing_branch": True, "release-*": {"protected": True}}},
+        )
+
+        project.protectedbranches.create.assert_called_once()
+
     def test_convert_user_and_group_names_to_ids(self):
         # Setup
         self.processor.gl = MagicMock()