gitlabform 0.0.540a0__py3-none-any.whl

gitlabform/configuration/transform.py

@@ -0,0 +1,259 @@
+import sys
+from logging import debug, info, critical
+from abc import ABC, abstractmethod
+from ez_yaml import ez_yaml
+from ruamel.yaml import YAML
+from types import SimpleNamespace
+
+from ruamel.yaml.comments import CommentedMap
+from yamlpath import Processor
+from yamlpath.exceptions import YAMLPathException
+from yamlpath.wrappers import ConsolePrinter
+
+from gitlabform.constants import EXIT_INVALID_INPUT, APPROVAL_RULE_NAME
+from gitlabform.configuration import Configuration
+from gitlabform.gitlab import AccessLevel
+from gitlabform.gitlab import GitLab
+
+# Configuration transformers are classes which take the input configuration as YAML and change it
+# to from the more user-friendly input to an output that is more applicable to passing to GitLab
+# over its API.
+#
+# For example, we want to operate on usernames in the configuration while GitLab sometimes operates
+# on user ids. Therefore, one of the transformers changes "user_id: <number>" into "user: <username>".
+
+
+class ConfigurationTransformers:
+    def __init__(self, gitlab: GitLab):
+        self.user_transformer = UserTransformer(gitlab)
+        self.group_transformer = GroupTransformer(gitlab)
+        self.implicit_name_transformer = ImplicitNameTransformer(gitlab)
+        self.access_level_transformer = AccessLevelsTransformer(gitlab)
+
+    def transform(self, configuration: Configuration) -> None:
+        config_before = ez_yaml.to_string(obj=configuration.config, options={})
+        debug(f"Config BEFORE transformations:\n{config_before}")
+
+        self.user_transformer.transform(configuration)
+        self.group_transformer.transform(configuration)
+        self.implicit_name_transformer.transform(configuration)
+        self.access_level_transformer.transform(configuration, last=True)
+
+        config_after = ez_yaml.to_string(obj=configuration.config, options={})
+        debug(f"Config AFTER transformations:\n{config_after}")
+
+
+class ConfigurationTransformer(ABC):
+    def transform(self, configuration: Configuration, last: bool = False) -> None:
+        self._do_transform(configuration)
+        if last:
+            self.convert_to_simple_types(configuration)
+
+    @abstractmethod
+    def _do_transform(self, configuration: Configuration) -> None:
+        pass
+
+    @staticmethod
+    def convert_to_simple_types(configuration: Configuration):
+        # we needed complex ruamel.yaml's types like ordereddict and CommentedSeq
+        # for transformations, but at the end convert them to simple dict and lists
+        # for easier to understand debug output and tests
+
+        config_yaml_string = ez_yaml.to_string(obj=configuration.config, options={})
+        simple_yaml_loader = YAML(typ="safe", pure=True)
+        configuration.config = simple_yaml_loader.load(config_yaml_string)
+
+
+class UserTransformer(ConfigurationTransformer):
+    def __init__(self, gitlab: GitLab):
+        self.gitlab = gitlab
+
+    def _do_transform(self, configuration: Configuration) -> None:
+        logging_args = SimpleNamespace(quiet=False, verbose=False, debug=False)
+        log = ConsolePrinter(logging_args)
+        processor = Processor(log, configuration.config)
+        info("Getting user ids for users defined in protect_environments config")
+        try:
+            for node_coordinate in processor.get_nodes(
+                "projects_and_groups.*.protected_environments.*.deploy_access_levels.user",
+                mustexist=True,
+            ):
+                user = node_coordinate.parent.pop("user")
+
+                node_coordinate.parent["user_id"] = self.gitlab._get_user_id(user)
+        except YAMLPathException as e:
+            # this just means that we haven't found any keys in YAML
+            # under the given path
+            pass
+
+        info("Getting user ids for users defined in merge_requests_approval_rules config")
+        try:
+            for node_coordinate in processor.get_nodes(
+                "**.merge_requests_approval_rules.*.users",
+                mustexist=True,
+            ):
+                user_ids = []
+                users = node_coordinate.parent.pop("users")
+                for user in users:
+                    user_id = self.gitlab._get_user_id(user)
+                    user_ids.append(user_id)
+                node_coordinate.parent["user_ids"] = user_ids
+        except YAMLPathException as e:
+            # this just means that we haven't found any keys in YAML
+            # under the given path
+            pass
+
+
+class GroupTransformer(ConfigurationTransformer):
+    def __init__(self, gitlab: GitLab):
+        self.gitlab = gitlab
+
+    def _do_transform(self, configuration: Configuration) -> None:
+        logging_args = SimpleNamespace(quiet=False, verbose=False, debug=False)
+        processor = Processor(ConsolePrinter(logging_args), configuration.config)
+
+        try:
+            for node_coordinate in processor.get_nodes(
+                "projects_and_groups.*.protected_environments.*.deploy_access_levels.group",
+                mustexist=True,
+            ):
+                group = node_coordinate.parent.pop("group")
+                node_coordinate.parent["group_id"] = self.gitlab._get_group_id(group)
+
+        except YAMLPathException as e:
+            # this just means that we haven't found any keys in YAML
+            # under the given path
+            pass
+
+        try:
+            for node_coordinate in processor.get_nodes(
+                "**.merge_requests_approval_rules.*.groups",
+                mustexist=True,
+            ):
+                group_ids = []
+                groups = node_coordinate.parent.pop("groups")
+                for group in groups:
+                    group_id = self.gitlab._get_group_id(group)
+                    group_ids.append(group_id)
+                node_coordinate.parent["group_ids"] = group_ids
+        except YAMLPathException:
+            # this just means that we haven't found any keys in YAML
+            # under the given path
+            pass
+
+
+class ImplicitNameTransformer(ConfigurationTransformer):
+    """
+    Creates a 'name' field that has the same value as the "scope" delimiter, e.g.:
+
+    ...
+      blah: # start of the cfg scope
+       name: blah # name to be used
+       smth_else: <...>
+
+    It's redundant, so this can be done as :
+
+    ...
+     foo: # a 'name' field will be created as -> name: foo
+       smth_else: <...>
+    """
+
+    def __init__(self, gitlab: GitLab):
+        # this transformer doesn't need to call gitlab
+        pass
+
+    def _do_transform(self, configuration: Configuration) -> None:
+        logging_args = SimpleNamespace(quiet=False, verbose=False, debug=False)
+        processor = Processor(ConsolePrinter(logging_args), configuration.config)
+
+        try:
+            for node_coordinate in processor.get_nodes(
+                "projects_and_groups.*.protected_environments.*",
+                mustexist=True,
+            ):
+                if type(node_coordinate.node) not in [CommentedMap, dict]:
+                    continue
+
+                node_coordinate.parent[node_coordinate.parentref]["name"] = node_coordinate.parentref
+        except YAMLPathException:
+            # this just means that we haven't found any keys in YAML
+            # under the given path
+            pass
+
+
+class AccessLevelsTransformer(ConfigurationTransformer):
+    """
+    Internally the app supports only numeric access levels, but for user-friendliness
+    this class allows providing them as strings and transforms these strings into
+    the appropriate numbers.
+    """
+
+    def __init__(self, gitlab: GitLab):
+        # this transformer doesn't need to call gitlab
+        pass
+
+    def _do_transform(self, configuration: Configuration):
+        logging_args = SimpleNamespace(quiet=False, verbose=False, debug=False)
+        processor = Processor(ConsolePrinter(logging_args), configuration.config)
+
+        # [.!<100] effectively means that the value is non-numerical
+        paths_to_hashes = [
+            # # branches, old syntax
+            "**.push_access_level[.!<100]",
+            "**.merge_access_level[.!<100]",
+            "**.unprotect_access_level[.!<100]",
+            # members & group members
+            "**.access_level[.!<100]",
+            "**.group_access[.!<100]",
+            # old syntax
+            "**.group_access_level[.!<100]",
+            # tags
+            "**.create_access_level[.!<100]",
+        ]
+
+        for path in paths_to_hashes:
+            try:
+                for node_coordinate in processor.get_nodes(path, mustexist=True):
+                    try:
+                        access_level_string = str(node_coordinate.node)
+                        node_coordinate.parent[node_coordinate.parentref] = AccessLevel.get_value(access_level_string)
+                    except KeyError:
+                        critical(
+                            f"Configuration string '{access_level_string}' is not one of the valid access levels:"
+                            f" {', '.join(AccessLevel.get_canonical_names())}"
+                        )
+                        sys.exit(EXIT_INVALID_INPUT)
+            except YAMLPathException:
+                # this just means that we haven't found any keys in YAML
+                # under the given path
+                pass
+
+        # these are different from the above, as they are elements of arrays,
+        # so we need different search query and an extra condition for
+        # transformation
+        paths_to_arrays = [
+            # # branches, new GitLab Premium syntax
+            "**.allowed_to_push.*.[access_level!<100]",
+            "**.allowed_to_merge.*.[access_level!<100]",
+            "**.allowed_to_unprotect.*.[access_level!<100]",
+        ]
+
+        for path in paths_to_arrays:
+            try:
+                for node_coordinate in processor.get_nodes(path, mustexist=True):
+                    if node_coordinate.parentref == "access_level":
+                        try:
+                            access_level_string = str(node_coordinate.node)
+                            node_coordinate.parent[node_coordinate.parentref] = AccessLevel.get_value(
+                                access_level_string
+                            )
+                        except KeyError:
+                            critical(
+                                f"Configuration string '{access_level_string}' is not one of the valid access levels:"
+                                f" {', '.join(AccessLevel.get_canonical_names())}"
+                            )
+                            sys.exit(EXIT_INVALID_INPUT)
+            except YAMLPathException:
+                # this just means that we haven't found any keys in YAML
+                # under the given path
+                pass

gitlabform/constants.py

@@ -0,0 +1,7 @@
+# f.e. bad syntax in the config file ~= "it's your fault" 😅
+EXIT_INVALID_INPUT = 1
+# f.e. when requests to GitLab fail ~= "it's not your fault" 😎
+EXIT_PROCESSING_ERROR = 2
+
+# legacy single approval rule name
+APPROVAL_RULE_NAME = "Approvers (configured using GitLabForm)"

gitlabform/gitlab/__init__.py

@@ -0,0 +1,108 @@
+import enum
+import inspect
+import logging
+
+from typing import List
+
+from gitlab import Gitlab as GitlabClient, GraphQL
+
+from gitlabform.gitlab.commits import GitLabCommits
+from gitlabform.gitlab.group_badges import GitLabGroupBadges
+from gitlabform.gitlab.group_ldap_links import GitLabGroupLDAPLinks
+from gitlabform.gitlab.merge_requests import GitLabMergeRequests
+from gitlabform.gitlab.pipelines import GitLabPipelines
+from gitlabform.gitlab.project_badges import GitLabProjectBadges
+from gitlabform.gitlab.project_deploy_keys import GitLabProjectDeployKeys
+from gitlabform.gitlab.project_protected_environments import (
+    GitLabProjectProtectedEnvironments,
+)
+from gitlabform.gitlab.project_merge_requests_approvals import (
+    GitLabProjectMergeRequestsApprovals,
+)
+from gitlabform.gitlab.python_gitlab import PythonGitlab
+
+
+@enum.unique
+class AccessLevel(enum.IntEnum):
+    NO_ACCESS = 0
+    MINIMAL = 5  # introduced in GitLab 13.5
+    GUEST = 10
+    PLANNER = 15  # introduced in GitLab 17.7
+    REPORTER = 20
+    DEVELOPER = 30
+    MAINTAINER = 40
+    OWNER = 50  # only for groups
+    ADMIN = 60
+
+    @classmethod
+    def group_levels(cls) -> List[int]:
+        return [level.value for level in AccessLevel if level <= 50]
+
+    @classmethod
+    def get_value(cls, name: str) -> int:
+        # for the above set of key names this is enough for an effectively fuzzy name matching
+        return AccessLevel[name.strip().upper().replace(" ", "_")].value
+
+    @classmethod
+    def get_canonical_names(cls) -> List[str]:
+        return [level.name.lower().replace("_", " ") for level in AccessLevel]
+
+
+class GitLab(
+    GitLabCommits,
+    GitLabMergeRequests,
+    GitLabGroupLDAPLinks,
+    GitLabGroupBadges,
+    GitLabPipelines,
+    GitLabProjectBadges,
+    GitLabProjectDeployKeys,
+    GitLabProjectProtectedEnvironments,
+    GitLabProjectMergeRequestsApprovals,
+):
+    pass
+
+
+class GitlabWrapper:
+    # Parameters accepted by python-gitlab's Gitlab.__init__
+    # Other config keys (like max_retries) are used elsewhere in gitlabform
+    # or passed to specific components like GraphQL
+    GITLAB_CLIENT_PARAMS = set(inspect.signature(GitlabClient.__init__).parameters.keys()) - {"self"}
+
+    # Parameters accepted by python-gitlab's GraphQL.__init__
+    GRAPHQL_PARAMS = set(inspect.signature(GraphQL.__init__).parameters.keys()) - {"self"}
+
+    def __init__(self, gitlabform: GitLab):
+        session = gitlabform.session
+
+        graphql_kwargs = {k: v for k, v in gitlabform.gitlab_config.items() if k in self.GRAPHQL_PARAMS}
+        graphql = GraphQL(**graphql_kwargs)
+
+        default_gitlab_kwargs = {
+            "retry_transient_errors": True,
+        }
+        renamed_gitlab_kwargs = {
+            # Bandit is used for security scanning and it complains about 'private_token' being
+            # a hardcoded secret. However, in this case we are just renaming a config key
+            # provided by the user to match the parameter name expected by python-gitlab.
+            # Hence, we can safely ignore this code security warning here.
+            "token": "private_token",  # nosec B105
+        }
+        extra_gitlab_kwargs = {
+            **default_gitlab_kwargs,
+            **{
+                k: v
+                for k, v in gitlabform.gitlab_config.items()
+                if k not in renamed_gitlab_kwargs and k in self.GITLAB_CLIENT_PARAMS
+            },
+            **{renamed_gitlab_kwargs[k]: v for k, v in gitlabform.gitlab_config.items() if k in renamed_gitlab_kwargs},
+        }
+
+        self._gitlab: PythonGitlab = PythonGitlab(
+            api_version="4",
+            graphql=graphql,
+            session=session,
+            **extra_gitlab_kwargs,
+        )
+
+    def get_gitlab(self):
+        return self._gitlab

gitlabform/gitlab/commits.py

@@ -0,0 +1,39 @@
+from gitlabform.gitlab.core import GitLabCore
+
+
+class GitLabCommits(GitLabCore):
+    def get_commit(self, project_and_group_name, sha):
+        return self._make_requests_to_api("projects/%s/repository/commits/%s", (project_and_group_name, sha))
+
+    def get_ahead_and_behind(self, project_and_group_name, protected_branch, feature_branch):
+        ahead = 0
+        behind = 0
+
+        response = self._make_requests_to_api(
+            "projects/%s/repository/compare?from=%s&to=%s",
+            (project_and_group_name, protected_branch, feature_branch),
+        )
+        if len(response) > 0:
+            ahead = len(response["commits"])
+
+        response = self._make_requests_to_api(
+            "projects/%s/repository/compare?from=%s&to=%s",
+            (project_and_group_name, feature_branch, protected_branch),
+        )
+        if len(response) > 0:
+            behind = len(response["commits"])
+
+        return ahead, behind
+
+    def get_last_commit(self, project_and_group_name, branch_name):
+        branch = self._make_requests_to_api("projects/%s/repository/branches/%s", (project_and_group_name, branch_name))
+        last_commit_hash = branch["commit"]["id"]
+        return self.get_commit(project_and_group_name, last_commit_hash)
+
+    def get_last_commit_attributes(self, project_and_group_name, branch):
+        commit = self.get_last_commit(project_and_group_name, branch)
+
+        # we want to read git's *commit date* instead of *author date*, so that "touching" the branch will invalidate
+        # its "getting older" counter
+
+        return commit["author_name"], commit["author_email"], commit["committed_date"]