github-org-manager 0.5.7__tar.gz → 0.7.1__tar.gz

{github_org_manager-0.5.7 → github_org_manager-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: github-org-manager
-Version: 0.5.7
+Version: 0.7.1
 Summary: Manage a GitHub Organization, its teams, repository permissions, and more
 License: Apache-2.0
 Keywords: github,github-management,permissions,access-control
@@ -76,7 +76,7 @@ Afterwards, the tool is executable with the command `gh-org-mgr`. The `--help` f
 
 Inside [`config/example`](./config/example), you can find an example configuration that shall help you to understand the structure:
 
-* `app.yaml`: Configuration necessary to run this tool
+* `app.yaml`: Configuration necessary to run this tool and controlling some behaviour
 * `org.yaml`: Organization-wide configuration
 * `teams/*.yaml`: Configuration concerning the teams of your organization.
 

{github_org_manager-0.5.7 → github_org_manager-0.7.1}/README.md

@@ -48,7 +48,7 @@ Afterwards, the tool is executable with the command `gh-org-mgr`. The `--help` f
 
 Inside [`config/example`](./config/example), you can find an example configuration that shall help you to understand the structure:
 
-* `app.yaml`: Configuration necessary to run this tool
+* `app.yaml`: Configuration necessary to run this tool and controlling some behaviour
 * `org.yaml`: Organization-wide configuration
 * `teams/*.yaml`: Configuration concerning the teams of your organization.
 

github_org_manager-0.7.1/gh_org_mgr/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2024 DB Systel GmbH
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Global init file"""
+
+from importlib.metadata import version
+
+__version__ = version("github-org-manager")

{github_org_manager-0.5.7 → github_org_manager-0.7.1}/gh_org_mgr/_gh_org.py

@@ -19,10 +19,18 @@ from github.GithubException import BadCredentialsException
 from github.NamedUser import NamedUser
 from github.Organization import Organization
 from github.Repository import Repository
+from github.Requester import Requester
 from github.Team import Team
 from jwt.exceptions import InvalidKeyError
 
 from ._gh_api import get_github_secrets_from_env, run_graphql_query
+from ._helpers import (
+    compare_two_dicts,
+    compare_two_lists,
+    dict_to_pretty_string,
+    sluggify_teamname,
+)
+from ._stats import OrgChanges
 
 
 @dataclass
@@ -47,6 +55,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
     configured_repos_collaborators: dict[str, dict[str, str]] = field(default_factory=dict)
     archived_repos: list[Repository] = field(default_factory=list)
     unconfigured_team_repo_permissions: dict[str, dict[str, str]] = field(default_factory=dict)
+    stats: OrgChanges = field(default_factory=OrgChanges)
 
     # Re-usable Constants
     TEAM_CONFIG_FIELDS: dict[str, dict[str, str | None]] = field(  # pylint: disable=invalid-name
@@ -61,12 +70,6 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
     # --------------------------------------------------------------------------
     # Helper functions
     # --------------------------------------------------------------------------
-    def _sluggify_teamname(self, team: str) -> str:
-        """Slugify a GitHub team name"""
-        # TODO: this is very naive, no other special chars are
-        # supported, or multiple spaces etc.
-        return team.replace(" ", "-")
-
     # amazonq-ignore-next-line
     def login(
         self, orgname: str, token: str = "", app_id: str | int = "", app_private_key: str = ""
@@ -117,88 +120,9 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
             "Current rate limit: %s/%s (reset: %s)", core.remaining, core.limit, core.reset
         )
 
-    def pretty_print_dict(self, dictionary: dict) -> str:
-        """Convert a dict to a pretty-printed output"""
-
-        # Censor sensible fields
-        def censor_half_string(string: str) -> str:
-            """Censor 50% of a string (rounded up)"""
-            half1 = int(len(string) / 2)
-            half2 = len(string) - half1
-            return string[:half1] + "*" * (half2)
-
-        sensible_keys = ["gh_token", "gh_app_private_key"]
-        for key in sensible_keys:
-            if value := dictionary.get(key, ""):
-                dictionary[key] = censor_half_string(value)
-
-        # Print dict nicely
-        def pretty(d, indent=0):
-            string = ""
-            for key, value in d.items():
-                string += "  " * indent + str(key) + ":\n"
-                if isinstance(value, dict):
-                    string += pretty(value, indent + 1)
-                else:
-                    string += "  " * (indent + 1) + str(value) + "\n"
-
-            return string
-
-        return pretty(dictionary)
-
     def pretty_print_dataclass(self) -> str:
         """Convert this dataclass to a pretty-printed output"""
-        return self.pretty_print_dict(asdict(self))
-
-    def compare_two_lists(self, list1: list[str], list2: list[str]):
-        """
-        Compares two lists of strings and returns a tuple containing elements
-        missing in each list and common elements.
-
-        Args:
-            list1 (list of str): The first list of strings.
-            list2 (list of str): The second list of strings.
-
-        Returns:
-            tuple: A tuple containing three lists:
-                1. The first list contains elements in `list2` that are missing in `list1`.
-                2. The second list contains elements that are present in both `list1` and `list2`.
-                3. The third list contains elements in `list1` that are missing in `list2`.
-
-        Example:
-            >>> list1 = ["apple", "banana", "cherry"]
-            >>> list2 = ["banana", "cherry", "date", "fig"]
-            >>> compare_lists(list1, list2)
-            (['date', 'fig'], ['banana', 'cherry'], ['apple'])
-        """
-        # Convert lists to sets for easier comparison
-        set1, set2 = set(list1), set(list2)
-
-        # Elements in list2 that are missing in list1
-        missing_in_list1 = list(set2 - set1)
-
-        # Elements present in both lists
-        common_elements = list(set1 & set2)
-
-        # Elements in list1 that are missing in list2
-        missing_in_list2 = list(set1 - set2)
-
-        # Return the result as a tuple
-        return (missing_in_list1, common_elements, missing_in_list2)
-
-    def compare_two_dicts(self, dict1: dict, dict2: dict) -> dict[str, dict[str, str | int | None]]:
-        """Compares two dictionaries. Assume that the keys are the same. Output
-        a dict with keys that have differing values"""
-        # Create an empty dictionary to store differences
-        differences = {}
-
-        # Iterate through the keys (assuming both dictionaries have the same keys)
-        for key in dict1:
-            # Compare the values for each key
-            if dict1[key] != dict2[key]:
-                differences[key] = {"dict1": dict1[key], "dict2": dict2[key]}
-
-        return differences
+        return dict_to_pretty_string(asdict(self), sensible_keys=["gh_token", "gh_app_private_key"])
 
     def _resolve_gh_username(self, username: str, teamname: str) -> NamedUser | None:
         """Turn a username into a proper GitHub user object"""
@@ -293,7 +217,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
             return
 
         # Get differences between the current and configured owners
-        owners_remove, owners_ok, owners_add = self.compare_two_lists(
+        owners_remove, owners_ok, owners_add = compare_two_lists(
             self.configured_org_owners, [user.login for user in self.current_org_owners]
         )
         # Compare configured (lower-cased) owners with lower-cased list of current owners
@@ -314,6 +238,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
         for user in owners_add:
             if gh_user := self._resolve_gh_username(user, "<org owners>"):
                 logging.info("Adding user '%s' as organization owner", gh_user.login)
+                self.stats.add_owner(gh_user.login)
                 if not dry:
                     self.org.add_to_members(gh_user, "admin")
 
@@ -325,6 +250,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                     "Will make them a normal member",
                     gh_user.login,
                 )
+                self.stats.degrade_owner(gh_user.login)
                 # Handle authenticated user being the same as the one you want to degrade
                 if self._is_user_authenticated_user(gh_user):
                     logging.warning(
@@ -370,9 +296,10 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
         for team, attributes in self.configured_teams.items():
             if team not in existent_team_names:
                 if parent := attributes.get("parent"):  # type: ignore
-                    parent_id = self.org.get_team_by_slug(self._sluggify_teamname(parent)).id
+                    parent_id = self.org.get_team_by_slug(sluggify_teamname(parent)).id
 
                     logging.info("Creating team '%s' with parent ID '%s'", team, parent_id)
+                    self.stats.create_team(team)
                     # NOTE: We do not specify any team settings (description etc)
                     # here, this will happen later
                     if not dry:
@@ -385,6 +312,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
 
                 else:
                     logging.info("Creating team '%s' without parent", team)
+                    self.stats.create_team(team)
                     if not dry:
                         self.org.create_team(
                             team,
@@ -410,7 +338,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
             # team coming from config, and valid string
             elif isinstance(parent, str) and parent:
                 team_config["parent_team_id"] = self.org.get_team_by_slug(
-                    self._sluggify_teamname(parent)
+                    sluggify_teamname(parent)
                 ).id
             # empty from string, so probably default value
             elif isinstance(parent, str) and not parent:
@@ -471,16 +399,17 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
             )
 
             # Compare settings and update if necessary
-            if differences := self.compare_two_dicts(configured_team_configs, current_team_configs):
+            if differences := compare_two_dicts(configured_team_configs, current_team_configs):
                 # Log differences
                 logging.info(
                     "Team settings for '%s' differ from the configuration. Updating them:",
                     team.name,
                 )
                 for setting, diff in differences.items():
-                    logging.info(
-                        "Setting '%s': '%s' --> '%s'", setting, diff["dict2"], diff["dict1"]
-                    )
+                    change_str = f"Setting '{setting}': '{diff['dict2']}' --> '{diff['dict1']}'"
+                    logging.info(change_str)
+                    self.stats.edit_team_config(team.name, new_config=change_str)
+
                 # Execute team setting changes
                 if not dry:
                     try:
@@ -489,7 +418,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                         logging.critical(
                             "Team '%s' settings could not be edited. Error: \n%s",
                             team.name,
-                            self.pretty_print_dict(exc.data),
+                            dict_to_pretty_string(exc.data),
                         )
                         sys.exit(1)
             else:
@@ -550,6 +479,10 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
         open_invitations = [user.login.lower() for user in self.org.invitations()]
 
         for team, team_attrs in self.current_teams.items():
+            # Ignore any team not being configured locally, will be handled later
+            if team.name not in self.configured_teams:
+                continue
+
             # Update current team members with dict[NamedUser, str (role)]
             team_attrs["members"] = self._get_current_team_members(team)
 
@@ -559,15 +492,6 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                 user.login.lower(): role for user, role in team_attrs["members"].items()
             }
 
-            # Handle the team not being configured locally
-            if team.name not in self.configured_teams:
-                logging.warning(
-                    "Team '%s' does not seem to be configured locally. "
-                    "Taking no action about this team at all",
-                    team.name,
-                )
-                continue
-
             # Get configuration from current team
             if team_configuration := self.configured_teams.get(team.name):
                 pass
@@ -616,6 +540,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                             team.name,
                             config_role,
                         )
+                        self.stats.pending_team_member(team=team.name, user=gh_user.login)
                         continue
 
                     logging.info(
@@ -624,6 +549,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                         team.name,
                         config_role,
                     )
+                    self.stats.add_team_member(team=team.name, user=gh_user.login)
                     if not dry:
                         self._add_or_update_user_in_team(team=team, user=gh_user, role=config_role)
 
@@ -638,6 +564,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                         team.name,
                         config_role,
                     )
+                    self.stats.change_team_member_role(team=team.name, user=gh_user.login)
                     if not dry:
                         self._add_or_update_user_in_team(team=team, user=gh_user, role=config_role)
 
@@ -656,6 +583,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                             gh_user.login,
                             team.name,
                         )
+                        self.stats.remove_team_member(team=team.name, user=gh_user.login)
                         if not dry:
                             team.remove_membership(gh_user)
                     else:
@@ -666,8 +594,38 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                             team.name,
                         )
 
-    def get_members_without_team(self) -> None:
-        """Get all organisation members without any team membership"""
+    def get_unconfigured_teams(
+        self, dry: bool = False, delete_unconfigured_teams: bool = False
+    ) -> None:
+        """Get all teams that are not configured locally and optionally remove them"""
+        # Get all teams that are not configured locally
+        unconfigured_teams: list[Team] = []
+        for team in self.current_teams:
+            if team.name not in self.configured_teams:
+                unconfigured_teams.append(team)
+
+        if unconfigured_teams:
+            if delete_unconfigured_teams:
+                for team in unconfigured_teams:
+                    logging.info("Deleting team '%s' as it is not configured locally", team.name)
+                    self.stats.delete_team(team=team.name, deleted=True)
+                    if not dry:
+                        team.delete()
+            else:
+                unconfigured_teams_str = [team.name for team in unconfigured_teams]
+                logging.warning(
+                    "The following teams of your GitHub organisation are not "
+                    "configured locally: %s. Taking no action about these teams.",
+                    ", ".join(unconfigured_teams_str),
+                )
+                for team in unconfigured_teams:
+                    self.stats.delete_team(team=team.name, deleted=False)
+
+    def get_members_without_team(
+        self, dry: bool = False, remove_members_without_team: bool = False
+    ) -> None:
+        """Get all organisation members without any team membership, and
+        optionally remove them"""
         # Combine org owners and org members
         all_org_members = set(self.org_members + self.current_org_owners)
 
@@ -676,18 +634,33 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
         for _, team_attrs in self.current_teams.items():
             for member in team_attrs.get("members", {}):
                 all_team_members_lst.append(member)
-        # Also add users that have just been added to a team, and unify them
-        all_team_members: set[NamedUser] = set(all_team_members_lst + self.newly_added_users)
+        # Also add org owners and users that have just been added to a team, and unify them
+        all_team_members: set[NamedUser] = set(
+            all_team_members_lst + self.newly_added_users + self.current_org_owners
+        )
 
         # Find members that are in org_members but not team_members
         members_without_team = all_org_members.difference(all_team_members)
 
         if members_without_team:
-            members_without_team_str = [user.login for user in members_without_team]
-            logging.warning(
-                "The following members of your GitHub organisation are not member of any team: %s",
-                ", ".join(members_without_team_str),
-            )
+            if remove_members_without_team:
+                for user in members_without_team:
+                    logging.info(
+                        "Removing user '%s' from organisation as they are not member of any team",
+                        user.login,
+                    )
+                    self.stats.remove_member_without_team(user=user.login, removed=True)
+                    if not dry:
+                        self.org.remove_from_membership(user)
+            else:
+                members_without_team_str = [user.login for user in members_without_team]
+                logging.warning(
+                    "The following members of your GitHub organisation are not "
+                    "member of any team: %s",
+                    ", ".join(members_without_team_str),
+                )
+                for user in members_without_team:
+                    self.stats.remove_member_without_team(user=user.login, removed=False)
 
     # --------------------------------------------------------------------------
     # Repos
@@ -720,7 +693,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
 
             # Convert team name to Team object
             try:
-                team = self.org.get_team_by_slug(self._sluggify_teamname(team_name))
+                team = self.org.get_team_by_slug(sluggify_teamname(team_name))
             # Team not found, probably because a new team should be created, but it's a dry-run
             except UnknownObjectException:
                 logging.debug(
@@ -729,12 +702,21 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                 )
                 # Initialise a new Team() object with the name, manually
                 team = Team(
-                    requester=None,  # type: ignore
+                    requester=Requester(
+                        auth=None,
+                        base_url="https://api.github.com",
+                        timeout=10,
+                        user_agent="",
+                        per_page=100,
+                        verify=True,
+                        retry=3,
+                        pool_size=200,
+                    ),
                     headers={},  # No headers required
                     attributes={
                         "id": 0,
                         "name": team_name,
-                        "slug": self._sluggify_teamname(team_name),
+                        "slug": sluggify_teamname(team_name),
                     },
                     completed=True,  # Mark as fully initialized
                 )
@@ -806,6 +788,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                     team.name,
                     perm,
                 )
+                self.stats.change_repo_team_permissions(repo=repo.name, team=team.name, perm=perm)
                 if not dry:
                     # Update permissions or newly add a team to a repo
                     team.update_team_repository(repo, perm)
@@ -831,6 +814,10 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                     self._document_unconfigured_team_repo_permissions(
                         team=team, team_permission=teams[team], repo_name=repo.name
                     )
+                    # Collect this status in the stats
+                    self.stats.document_unconfigured_team_permissions(
+                        team=team.name, repo=repo.name, perm=teams[team]
+                    )
                     # Abort handling the repo sync as we don't touch unconfigured teams
                     continue
                 # Handle: Team is configured, but contains no config
@@ -849,6 +836,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                 # Remove if any mismatch has been found
                 if remove:
                     logging.info("Removing team '%s' from repository '%s'", team.name, repo.name)
+                    self.stats.remove_team_from_repo(repo=repo.name, team=team.name)
                     if not dry:
                         team.remove_from_repos(repo)
 
@@ -1294,5 +1282,6 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                     )
 
                     # Remove collaborator
+                    self.stats.remove_repo_collaborator(repo=repo.name, user=username)
                     if not dry:
                         repo.remove_from_collaborators(username)

github_org_manager-0.7.1/gh_org_mgr/_helpers.py

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: 2025 DB Systel GmbH
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Helper functions"""
+
+import logging
+import sys
+from dataclasses import asdict
+
+
+def configure_logger(verbose: bool = False, debug: bool = False) -> logging.Logger:
+    """Set logging options"""
+    log = logging.getLogger()
+    logging.basicConfig(
+        encoding="utf-8",
+        format="[%(asctime)s] %(levelname)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    if debug:
+        log.setLevel(logging.DEBUG)
+    elif verbose:
+        log.setLevel(logging.INFO)
+    else:
+        log.setLevel(logging.WARNING)
+
+    return log
+
+
+def log_progress(message: str) -> None:
+    """Log progress messages to stderr"""
+    # Clear line if no message is given
+    if not message:
+        sys.stderr.write("\r\033[K")
+        sys.stderr.flush()
+    else:
+        sys.stderr.write(f"\r\033[K⏳ {message}")
+        sys.stderr.flush()
+
+
+def sluggify_teamname(team: str) -> str:
+    """Slugify a GitHub team name"""
+    # TODO: this is very naive, no other special chars are
+    # supported, or multiple spaces etc.
+    return team.replace(" ", "-")
+
+
+def compare_two_lists(list1: list[str], list2: list[str]):
+    """
+    Compares two lists of strings and returns a tuple containing elements
+    missing in each list and common elements.
+
+    Args:
+        list1 (list of str): The first list of strings.
+        list2 (list of str): The second list of strings.
+
+    Returns:
+        tuple: A tuple containing three lists:
+            1. The first list contains elements in `list2` that are missing in `list1`.
+            2. The second list contains elements that are present in both `list1` and `list2`.
+            3. The third list contains elements in `list1` that are missing in `list2`.
+
+    Example:
+        >>> list1 = ["apple", "banana", "cherry"]
+        >>> list2 = ["banana", "cherry", "date", "fig"]
+        >>> compare_lists(list1, list2)
+        (['date', 'fig'], ['banana', 'cherry'], ['apple'])
+    """
+    # Convert lists to sets for easier comparison
+    set1, set2 = set(list1), set(list2)
+
+    # Elements in list2 that are missing in list1
+    missing_in_list1 = list(set2 - set1)
+
+    # Elements present in both lists
+    common_elements = list(set1 & set2)
+
+    # Elements in list1 that are missing in list2
+    missing_in_list2 = list(set1 - set2)
+
+    # Return the result as a tuple
+    return (missing_in_list1, common_elements, missing_in_list2)
+
+
+def compare_two_dicts(dict1: dict, dict2: dict) -> dict[str, dict[str, str | int | None]]:
+    """Compares two dictionaries. Assume that the keys are the same. Output
+    a dict with keys that have differing values"""
+    # Create an empty dictionary to store differences
+    differences = {}
+
+    # Iterate through the keys (assuming both dictionaries have the same keys)
+    for key in dict1:
+        # Compare the values for each key
+        if dict1[key] != dict2[key]:
+            differences[key] = {"dict1": dict1[key], "dict2": dict2[key]}
+
+    return differences
+
+
+def dict_to_pretty_string(dictionary: dict, sensible_keys: None | list[str] = None) -> str:
+    """Convert a dict to a pretty-printed output"""
+
+    # Censor sensible fields
+    def censor_half_string(string: str) -> str:
+        """Censor 50% of a string (rounded up)"""
+        half1 = int(len(string) / 2)
+        half2 = len(string) - half1
+        return string[:half1] + "*" * (half2)
+
+    if sensible_keys is None:
+        sensible_keys = []
+    for key in sensible_keys:
+        if value := dictionary.get(key, ""):
+            dictionary[key] = censor_half_string(value)
+
+    # Print dict nicely
+    def pretty(d, indent=0):
+        string = ""
+        for key, value in d.items():
+            string += "  " * indent + str(key) + ":\n"
+            if isinstance(value, dict):
+                string += pretty(value, indent + 1)
+            else:
+                string += "  " * (indent + 1) + str(value) + "\n"
+
+        return string
+
+    return pretty(dictionary)
+
+
+def pretty_print_dataclass(dc):
+    """Convert dataclass to a pretty-printed output"""
+    dict_to_pretty_string(asdict(dc))
+
+
+def implement_changes_into_class(dc_object, **changes: bool | str | list[str]):
+    """Smartly add changes to a (data)class object"""
+    for attribute, value in changes.items():
+        current_value = getattr(dc_object, attribute)
+        # attribute is list
+        if isinstance(current_value, list):
+            # input change is list
+            if isinstance(value, list):
+                current_value.extend(value)
+            # input change is not list
+            else:
+                current_value.append(value)
+        # All other cases, bool
+        else:
+            setattr(dc_object, attribute, value)
+
+    return dc_object

github_org_manager-0.7.1/gh_org_mgr/_stats.py

@@ -0,0 +1,258 @@
+# SPDX-FileCopyrightText: 2025 DB Systel GmbH
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Dataclasses and functions for statistics"""
+
+import json
+from dataclasses import dataclass, field
+
+from ._helpers import implement_changes_into_class
+
+
+@dataclass
+class TeamChanges:  # pylint: disable=too-many-instance-attributes
+    """Dataclass holding information about the changes made to a team"""
+
+    newly_created: bool = False
+    deleted: bool = False
+    unconfigured: bool = False
+    changed_config: list[str] = field(default_factory=list)
+    added_members: list[str] = field(default_factory=list)
+    changed_members_role: list[str] = field(default_factory=list)
+    removed_members: list[str] = field(default_factory=list)
+    pending_members: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RepoChanges:  # pylint: disable=too-many-instance-attributes
+    """Dataclass holding information about the changes made to a repository"""
+
+    changed_permissions_for_teams: list[str] = field(default_factory=list)
+    removed_teams: list[str] = field(default_factory=list)
+    unconfigured_teams_with_permissions: list[str] = field(default_factory=list)
+    removed_collaborators: list[str] = field(default_factory=list)
+
+
+@dataclass
+class OrgChanges:  # pylint: disable=too-many-instance-attributes
+    """Dataclass holding general statistics about the changes made to the organization"""
+
+    dry: bool = False
+    added_owners: list[str] = field(default_factory=list)
+    degraded_owners: list[str] = field(default_factory=list)
+    members_without_team: list[str] = field(default_factory=list)
+    removed_members: list[str] = field(default_factory=list)
+    teams: dict[str, TeamChanges] = field(default_factory=dict)
+    repos: dict[str, RepoChanges] = field(default_factory=dict)
+
+    # --------------------------------------------------------------------------
+    # Owners
+    # --------------------------------------------------------------------------
+    def add_owner(self, user: str) -> None:
+        """User has been added as owner"""
+        self.added_owners.append(user)
+
+    def degrade_owner(self, user: str) -> None:
+        """User has been degraded from owner to member"""
+        self.degraded_owners.append(user)
+
+    # --------------------------------------------------------------------------
+    # Teams
+    # --------------------------------------------------------------------------
+    def update_team(self, team_name: str, **changes: bool | str | list[str]) -> None:
+        """Update team changes"""
+        # Initialise team if not present
+        if team_name not in self.teams:
+            self.teams[team_name] = TeamChanges()
+
+        implement_changes_into_class(dc_object=self.teams[team_name], **changes)
+
+    def create_team(self, team: str) -> None:
+        """Team has been created"""
+        self.update_team(team_name=team, newly_created=True)
+
+    def edit_team_config(self, team: str, new_config: str) -> None:
+        """Team config has been changed"""
+        self.update_team(team_name=team, changed_config=new_config)
+
+    def delete_team(self, team: str, deleted: bool) -> None:
+        """Teams are not configured"""
+        self.update_team(team_name=team, unconfigured=True, deleted=deleted)
+
+    # --------------------------------------------------------------------------
+    # Members
+    # --------------------------------------------------------------------------
+    def add_team_member(self, team: str, user: str) -> None:
+        """User has been added to team"""
+        self.update_team(team_name=team, added_members=user)
+
+    def change_team_member_role(self, team: str, user: str) -> None:
+        """User role has been changed in team"""
+        self.update_team(team_name=team, changed_members_role=user)
+
+    def pending_team_member(self, team: str, user: str) -> None:
+        """User has a pending invitation"""
+        self.update_team(team_name=team, pending_members=user)
+
+    def remove_team_member(self, team: str, user: str) -> None:
+        """User has been removed from team"""
+        self.update_team(team_name=team, removed_members=user)
+
+    def remove_member_without_team(self, user: str, removed: bool) -> None:
+        """User is not in any team"""
+        self.members_without_team.append(user)
+        if removed:
+            self.removed_members.append(user)
+
+    # --------------------------------------------------------------------------
+    # Repos
+    # --------------------------------------------------------------------------
+    def update_repo(self, repo_name: str, **changes: bool | str | list[str]) -> None:
+        """Update team changes"""
+        # Initialise repo if not present
+        if repo_name not in self.teams:
+            self.repos[repo_name] = RepoChanges()
+
+        implement_changes_into_class(dc_object=self.repos[repo_name], **changes)
+
+    def change_repo_team_permissions(self, repo: str, team: str, perm: str) -> None:
+        """Team permissions have been changed for a repo"""
+        self.update_repo(repo_name=repo, changed_permissions_for_teams=f"{team}: {perm}")
+
+    def remove_team_from_repo(self, repo: str, team: str) -> None:
+        """Team has been removed form a repo"""
+        self.update_repo(repo_name=repo, removed_teams=team)
+
+    def document_unconfigured_team_permissions(self, repo: str, team: str, perm: str) -> None:
+        """Unconfigured team has permissions on repo"""
+        self.update_repo(repo_name=repo, unconfigured_teams_with_permissions=f"{team}: {perm}")
+
+    def remove_repo_collaborator(self, repo: str, user: str) -> None:
+        """Remove collaborator"""
+        self.update_repo(repo_name=repo, removed_collaborators=user)
+
+    # --------------------------------------------------------------------------
+    # Output
+    # --------------------------------------------------------------------------
+    def changes_into_dict(self) -> dict:
+        """Convert dataclass to dict, and only use classes that are not empty/False"""
+        changes_dict: dict[str, list[str] | dict] = {
+            key: value  # type: ignore
+            for key, value in {
+                "dry": self.dry,
+                "added_owners": self.added_owners,
+                "degraded_owners": self.degraded_owners,
+                "members_without_team": self.members_without_team,
+                "removed_members": self.removed_members,
+                "teams": self.teams,
+                "repos": self.repos,
+            }.items()
+            if value  # Exclude empty values
+        }
+
+        team_changes: dict[str, TeamChanges] = changes_dict.get("teams", {})  # type: ignore
+        repo_changes: dict[str, RepoChanges] = changes_dict.get("repos", {})  # type: ignore
+
+        for team, tchanges in team_changes.items():
+            new_changes = {
+                key: value
+                for key, value in tchanges.__dict__.items()
+                if value  # Exclude empty values
+            }
+            team_changes[team] = new_changes  # type: ignore
+        changes_dict["teams"] = team_changes
+
+        for repo, rchanges in repo_changes.items():
+            new_changes = {
+                key: value
+                for key, value in rchanges.__dict__.items()
+                if value  # Exclude empty values
+            }
+            repo_changes[repo] = new_changes  # type: ignore
+        changes_dict["repos"] = repo_changes
+
+        return changes_dict
+
+    def print_changes(  # pylint: disable=too-many-branches, too-many-statements
+        self, orgname: str, output: str, dry: bool
+    ) -> None:
+        """Print the changes, either in pretty format or as JSON"""
+
+        # Add dry run information to stats dataclass
+        self.dry = dry
+
+        # Output in the requested format
+        if output == "json":
+            changes_dict = self.changes_into_dict()
+            print(json.dumps(changes_dict, indent=2))
+        else:
+            output = (
+                f"#-------------------------------------{len(orgname)*'-'}\n"
+                f"# Changes made to GitHub organisation {orgname}\n"
+                f"#-------------------------------------{len(orgname)*'-'}\n\n"
+            )
+            if dry:
+                output += "⚠️ Dry-run mode, no changes executed\n\n"
+            if self.added_owners:
+                output += f"➕ Added owners: {', '.join(self.added_owners)}\n"
+            if self.degraded_owners:
+                output += f"🔻 Degraded owners: {', '.join(self.degraded_owners)}\n"
+            if self.members_without_team:
+                output += f"⚠️ Members without team: {', '.join(self.members_without_team)}\n"
+            if self.removed_members:
+                output += (
+                    f"❌ Members removed from organisation: {', '.join(self.removed_members)}\n"
+                )
+            if self.teams:
+                output += "\n🤝 Team Changes:\n"
+                for team, tchanges in self.teams.items():
+                    output += f"  🔹 {team}:\n"
+                    if tchanges.unconfigured:
+                        output += "    ⚠️ Is/was unconfigured\n"
+                    if tchanges.newly_created:
+                        output += "    🆕 Has been created\n"
+                    if tchanges.deleted:
+                        output += "    ❌ Has been deleted\n"
+                    if tchanges.changed_config:
+                        output += "    🔧 Changed config:\n"
+                        for item in tchanges.changed_config:
+                            output += f"      - {item}\n"
+                    if tchanges.added_members:
+                        output += "    ➕ Added members:\n"
+                        for item in tchanges.added_members:
+                            output += f"      - {item}\n"
+                    if tchanges.changed_members_role:
+                        output += '    🔄 Changed members role:"'
+                        for item in tchanges.changed_members_role:
+                            output += f"      - {item}\n"
+                    if tchanges.removed_members:
+                        output += "    ❌ Removed members:\n"
+                        for item in tchanges.removed_members:
+                            output += f"      - {item}\n"
+                    if tchanges.pending_members:
+                        output += "    ⏳ Pending members:\n"
+                        for item in tchanges.pending_members:
+                            output += f"      - {item}\n"
+            if self.repos:
+                output += "\n📂 Repository Changes:\n"
+                for repo, rchanges in self.repos.items():
+                    output += f"  🔹 {repo}:\n"
+                    if rchanges.changed_permissions_for_teams:
+                        output += "    🔧 Changed permissions for teams:\n"
+                        for item in rchanges.changed_permissions_for_teams:
+                            output += f"      - {item}\n"
+                    if rchanges.removed_teams:
+                        output += "    ❌ Removed teams:\n"
+                        for item in rchanges.removed_teams:
+                            output += f"      - {item}\n"
+                    if rchanges.unconfigured_teams_with_permissions:
+                        output += "    ⚠️ Unconfigured teams with permissions:\n"
+                        for item in rchanges.unconfigured_teams_with_permissions:
+                            output += f"      - {item}\n"
+                    if rchanges.removed_collaborators:
+                        output += "    ❌ Removed collaborators:\n"
+                        for item in rchanges.removed_collaborators:
+                            output += f"      - {item}\n"
+
+            print(output.strip())

{github_org_manager-0.5.7 → github_org_manager-0.7.1}/gh_org_mgr/manage.py

@@ -8,9 +8,10 @@ import argparse
 import logging
 import sys
 
-from . import __version__, configure_logger
+from . import __version__
 from ._config import parse_config_files
 from ._gh_org import GHorg
+from ._helpers import configure_logger, log_progress
 from ._setup_team import setup_team
 
 # Main parser with root-level flags
@@ -26,7 +27,8 @@ subparsers = parser.add_subparsers(dest="command", help="Available commands", re
 
 # Common flags, usable for all effective subcommands
 common_flags = argparse.ArgumentParser(add_help=False)  # No automatic help to avoid duplication
-common_flags.add_argument("--debug", action="store_true", help="Get verbose logging output")
+common_flags.add_argument("-v", "--verbose", action="store_true", help="Get INFO logging output")
+common_flags.add_argument("-vv", "--debug", action="store_true", help="Get DEBUG logging output")
 
 # Sync commands
 parser_sync = subparsers.add_parser(
@@ -40,6 +42,13 @@ parser_sync.add_argument(
     required=True,
     help="Path to the directory in which the configuration of an GitHub organisation is located",
 )
+parser_sync.add_argument(
+    "-o",
+    "--output",
+    help="Output format for report",
+    choices=["json", "text"],
+    default="text",
+)
 parser_sync.add_argument("--dry", action="store_true", help="Do not make any changes at GitHub")
 parser_sync.add_argument(
     "-A",
@@ -88,14 +97,15 @@ def main():
     # Process arguments
     args = parser.parse_args()
 
-    configure_logger(args.debug)
+    configure_logger(verbose=args.verbose, debug=args.debug)
 
     # Sync command
     if args.command == "sync":
+        log_progress("Preparing...")
         if args.dry:
             logging.info("Dry-run mode activated, will not make any changes at GitHub")
         if args.force:
-            logging.info("Force mode activated, will make potentially dangerous actions")
+            logging.warning("Force mode activated, will make potentially dangerous actions")
 
         org = GHorg()
 
@@ -122,25 +132,47 @@ def main():
         org.ratelimit()
 
         # Synchronise organisation owners
+        log_progress("Synchronising organisation owners...")
         org.sync_org_owners(dry=args.dry, force=args.force)
         # Create teams that aren't present at Github yet
+        log_progress("Creating missing teams...")
         org.create_missing_teams(dry=args.dry)
         # Configure general settings of teams
+        log_progress("Configuring team settings...")
         org.sync_current_teams_settings(dry=args.dry)
         # Synchronise the team memberships
+        log_progress("Synchronising team memberships...")
         org.sync_teams_members(dry=args.dry)
-        # Report about organisation members that do not belong to any team
-        org.get_members_without_team()
+        # Report and act on teams that are not configured locally
+        log_progress("Checking for unconfigured teams...")
+        org.get_unconfigured_teams(
+            dry=args.dry,
+            delete_unconfigured_teams=cfg_app.get("delete_unconfigured_teams", False),
+        )
+        # Report and act on organisation members that do not belong to any team
+        log_progress("Checking for members without team...")
+        org.get_members_without_team(
+            dry=args.dry,
+            remove_members_without_team=cfg_app.get("remove_members_without_team", False),
+        )
         # Synchronise the permissions of teams for all repositories
+        log_progress("Synchronising team permissions...")
         org.sync_repo_permissions(dry=args.dry, ignore_archived=args.ignore_archived)
         # Remove individual collaborator permissions if they are higher than the one
         # from team membership (or if they are in no configured team at all)
+        log_progress("Synchronising individual collaborator permissions...")
         org.sync_repo_collaborator_permissions(dry=args.dry)
 
         # Debug output
+        log_progress("")  # clear progress
         logging.debug("Final dataclass:\n%s", org.pretty_print_dataclass())
         org.ratelimit()
 
+        # Print changes
+        org.stats.print_changes(
+            orgname=cfg_org.get("org_name", ""), output=args.output, dry=args.dry
+        )
+
     # Setup Team command
     elif args.command == "setup-team":
         setup_team(team_name=args.name, config_path=args.config, file_path=args.file)

{github_org_manager-0.5.7 → github_org_manager-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "github-org-manager"
-version = "0.5.7"
+version = "0.7.1"
 description = "Manage a GitHub Organization, its teams, repository permissions, and more"
 authors = ["Max Mehl <max.mehl@deutschebahn.com>"]
 readme = "README.md"
@@ -39,7 +39,7 @@ mypy = "^1.9.0"
 pylint = "^3.1.0"
 types-pyyaml = "^6.0.12.20240311"
 types-requests = "^2.32.0.20240712"
-bump-my-version = "^0.30.0"
+bump-my-version = "^1.0.0"
 
 [build-system]
 requires = ["poetry-core"]

github_org_manager-0.5.7/gh_org_mgr/__init__.py

@@ -1,26 +0,0 @@
-# SPDX-FileCopyrightText: 2024 DB Systel GmbH
-#
-# SPDX-License-Identifier: Apache-2.0
-
-"""Global init file"""
-
-import logging
-from importlib.metadata import version
-
-__version__ = version("github-org-manager")
-
-
-def configure_logger(debug: bool = False) -> logging.Logger:
-    """Set logging options"""
-    log = logging.getLogger()
-    logging.basicConfig(
-        encoding="utf-8",
-        format="[%(asctime)s] %(levelname)s: %(message)s",
-        datefmt="%Y-%m-%d %H:%M:%S",
-    )
-    if debug:
-        log.setLevel(logging.DEBUG)
-    else:
-        log.setLevel(logging.INFO)
-
-    return log