github-org-manager 0.7.3__tar.gz → 0.7.5__tar.gz

{github_org_manager-0.7.3 → github_org_manager-0.7.5}/PKG-INFO

@@ -1,8 +1,13 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: github-org-manager
-Version: 0.7.3
+Version: 0.7.5
 Summary: Manage a GitHub Organization, its teams, repository permissions, and more
 License: Apache-2.0
+License-File: LICENSE.txt
+License-File: LICENSES/Apache-2.0.txt
+License-File: LICENSES/CC-BY-4.0.txt
+License-File: LICENSES/CC0-1.0.txt
+License-File: LICENSES/MIT.txt
 Keywords: github,github-management,permissions,access-control
 Author: Max Mehl
 Author-email: max.mehl@deutschebahn.com
@@ -17,12 +22,14 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Version Control :: Git
 Classifier: Topic :: Utilities
-Requires-Dist: pygithub (>=2.7.0,<3.0.0)
+Requires-Dist: jsonschema (>=4.25.1,<5.0.0)
+Requires-Dist: pygithub (>=2.8.1,<3.0.0)
 Requires-Dist: python-slugify (>=8.0.4,<9.0.0)
-Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
-Requires-Dist: requests (>=2.32.4,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
 Project-URL: Repository, https://github.com/OpenRailAssociation/github-org-manager
 Description-Content-Type: text/markdown
 

{github_org_manager-0.7.3 → github_org_manager-0.7.5}/gh_org_mgr/_config.py

@@ -11,6 +11,8 @@ import sys
 from typing import Any
 
 import yaml
+from jsonschema import FormatChecker, validate
+from jsonschema.exceptions import ValidationError
 
 # Global files with settings for the app and org, e.g. GitHub token and org name
 ORG_CONFIG_FILE = r"org\.ya?ml"
@@ -18,6 +20,84 @@ APP_CONFIG_FILE = r"app\.ya?ml"
 TEAM_CONFIG_DIR = "teams"
 TEAM_CONFIG_FILES = r".+\.ya?ml"
 
+# Schemas for config validation
+APP_CONFIG_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "github_token": {"type": "string"},
+        "github_app_id": {"type": "integer"},
+        "github_app_private_key": {"type": "string"},
+        "remove_members_without_team": {"type": "boolean"},
+        "delete_unconfigured_teams": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+ORG_CONFIG_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "org_name": {"type": "string"},
+        "org_owners": {
+            "type": "array",
+            "items": {"type": "string"},
+            "minItems": 1,
+        },
+        "defaults": {
+            "type": "object",
+            "properties": {
+                "team": {
+                    "type": "object",
+                    "properties": {
+                        "description": {"type": "string"},
+                        "privacy": {"type": "string", "enum": ["secret", "closed"]},
+                        "notification_setting": {
+                            "type": "string",
+                            "enum": ["notifications_enabled", "notifications_disabled"],
+                        },
+                    },
+                    "additionalProperties": False,
+                }
+            },
+            "additionalProperties": False,
+        },
+    },
+    "additionalProperties": False,
+    "required": ["org_name", "org_owners"],
+}
+TEAM_CONFIG_SCHEMA = {
+    "type": "object",
+    "patternProperties": {
+        "^[a-zA-Z0-9 _\\-]+$": {
+            "type": "object",
+            "properties": {
+                "description": {"type": "string"},
+                "privacy": {"type": "string", "enum": ["secret", "closed"]},
+                "notification_setting": {
+                    "type": "string",
+                    "enum": ["notifications_enabled", "notifications_disabled"],
+                },
+                "maintainer": {
+                    "oneOf": [{"type": "null"}, {"type": "array", "items": {"type": "string"}}]
+                },
+                "member": {
+                    "oneOf": [{"type": "null"}, {"type": "array", "items": {"type": "string"}}]
+                },
+                "parent": {"type": "string"},
+                "repos": {
+                    "type": "object",
+                    "propertyNames": {"type": "string"},
+                    "additionalProperties": {
+                        "type": "string",
+                        "enum": ["pull", "triage", "push", "maintain", "admin"],
+                    },
+                },
+            },
+            "additionalProperties": False,
+        }
+    },
+    "additionalProperties": False,
+    "required": [],
+}
+
 
 def _find_matching_files(directory: str, pattern: str, only_one: bool = False) -> list[str]:
     """
@@ -85,6 +165,16 @@ def _read_config_file(file: str) -> dict:
     return config
 
 
+def _validate_config_schema(file: str, cfg: dict, schema: dict) -> None:
+    """Validate the config against a JSON schema"""
+    try:
+        validate(instance=cfg, schema=schema, format_checker=FormatChecker())
+    except ValidationError as e:
+        logging.critical("Config validation of file %s failed: %s", file, e.message)
+        raise ValueError(e) from None
+    logging.debug("Config in file %s validated successfully against schema.", file)
+
+
 def parse_config_files(path: str) -> tuple[dict[str, str | dict[str, str]], dict, dict]:
     """Parse all relevant files in the configuration directory. Returns a tuple
     of org config, app config, and merged teams config"""
@@ -95,7 +185,9 @@ def parse_config_files(path: str) -> tuple[dict[str, str | dict[str, str]], dict
 
     # Read and parse config files for app and org
     cfg_app = _read_config_file(cfg_app_files[0])
+    _validate_config_schema(file=cfg_app_files[0], cfg=cfg_app, schema=APP_CONFIG_SCHEMA)
     cfg_org = _read_config_file(cfg_org_files[0])
+    _validate_config_schema(file=cfg_org_files[0], cfg=cfg_org, schema=ORG_CONFIG_SCHEMA)
 
     # For the teams config files, we parse and combine them as there may be multiple
     cfg_teams: dict[str, Any] = {}
@@ -103,6 +195,7 @@ def parse_config_files(path: str) -> tuple[dict[str, str | dict[str, str]], dict
     # Compare their keys (team names). They must not be defined multiple times!
     for cfg_team_file in cfg_teams_files:
         cfg = _read_config_file(cfg_team_file)
+        _validate_config_schema(file=cfg_team_file, cfg=cfg, schema=TEAM_CONFIG_SCHEMA)
         if overlap := set(cfg_teams.keys()) & set(cfg.keys()):
             logging.critical(
                 "The config file '%s' contains keys that are also defined in "

{github_org_manager-0.7.3 → github_org_manager-0.7.5}/gh_org_mgr/_gh_org.py

@@ -8,14 +8,12 @@ import logging
 import sys
 from dataclasses import asdict, dataclass, field
 
-from github import (
-    Auth,
-    Github,
+from github import Auth, Github, GithubIntegration
+from github.GithubException import (
+    BadCredentialsException,
     GithubException,
-    GithubIntegration,
     UnknownObjectException,
 )
-from github.GithubException import BadCredentialsException
 from github.NamedUser import NamedUser
 from github.Organization import Organization
 from github.Repository import Repository
@@ -47,6 +45,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
     configured_org_owners: list[str] = field(default_factory=list)
     org_members: list[NamedUser] = field(default_factory=list)
     current_teams: dict[Team, dict] = field(default_factory=dict)
+    current_teams_str: list[str] = field(default_factory=list)
     configured_teams: dict[str, dict | None] = field(default_factory=dict)
     newly_added_users: list[NamedUser] = field(default_factory=list)
     current_repos_teams: dict[Repository, dict[Team, str]] = field(default_factory=dict)
@@ -54,6 +53,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
     current_repos_collaborators: dict[Repository, dict[str, str]] = field(default_factory=dict)
     configured_repos_collaborators: dict[str, dict[str, str]] = field(default_factory=dict)
     archived_repos: list[Repository] = field(default_factory=list)
+    unconfigured_teams: list[Team] = field(default_factory=list)
     unconfigured_team_repo_permissions: dict[str, dict[str, str]] = field(default_factory=dict)
     stats: OrgChanges = field(default_factory=OrgChanges)
 
@@ -84,8 +84,9 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
 
         # Decide how to login. If app set, prefer this
         if self.gh_app_id and self.gh_app_private_key:
-            logging.debug("Logging in via app %s", self.gh_app_id)
-            auth = Auth.AppAuth(app_id=self.gh_app_id, private_key=self.gh_app_private_key)
+            gh_app_id_sanitized = str(self.gh_app_id).strip("'").strip('"')
+            logging.debug("Logging in via app %s", gh_app_id_sanitized)
+            auth = Auth.AppAuth(app_id=gh_app_id_sanitized, private_key=self.gh_app_private_key)
             app = GithubIntegration(auth=auth)
             try:
                 installation = app.get_org_installation(org=orgname)
@@ -202,9 +203,16 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
         return True
 
     def _is_user_authenticated_user(self, user: NamedUser) -> bool:
-        """Check if a given NamedUser is the authenticated user"""
-        if user.login == self.gh.get_user().login:
-            return True
+        """Check if a given NamedUser is the authenticated user. If logging in via App, this will
+        always return False, as the authenticated user is the App itself"""
+        try:
+            if user.login == self.gh.get_user().login:
+                return True
+        except GithubException as e:
+            if e.status == 403 and "Resource not accessible by integration" in str(e):
+                logging.debug("Cannot check if user is authenticated, as this is an App login")
+                return False
+            raise
         return False
 
     def sync_org_owners(self, dry: bool = False, force: bool = False) -> None:
@@ -283,20 +291,78 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
         """Get teams of the existing organisation"""
         for team in list(self.org.get_teams()):
             self.current_teams[team] = {"members": {}, "repos": {}}
+        self.current_teams_str = [team.name for team in self.current_teams]
 
-    def create_missing_teams(self, dry: bool = False):
-        """Find out which teams are configured but not part of the org yet"""
+    def ensure_team_hierarchy(self) -> None:
+        """Check if all configured parent teams make sense: either they exist already or will be
+        created during this run"""
 
         # Get list of current teams
         self._get_current_teams()
 
-        # Get the names of the existing teams
-        existent_team_names = [team.name for team in self.current_teams]
+        # First, check whether all configured parent teams exist or will be created
+        for team, attributes in self.configured_teams.items():
+            if parent := attributes.get("parent"):  # type: ignore
+                if parent not in self.configured_teams:
+                    if parent not in self.current_teams_str:
+                        logging.critical(
+                            "The team '%s' is configured with parent team '%s', but this parent "
+                            "team does not exist and is not configured to be created. "
+                            "Cannot continue.",
+                            team,
+                            parent,
+                        )
+                        sys.exit(1)
+                    else:
+                        logging.debug(
+                            "The team '%s' is configured with parent team '%s', "
+                            "which already exists",
+                            team,
+                            parent,
+                        )
+                else:
+                    logging.debug(
+                        "The team '%s' is configured with parent team '%s', "
+                        "which will be created during this run",
+                        team,
+                        parent,
+                    )
+
+        # Second, order the teams in a way that parent teams are created before child teams
+        ordered_teams: dict[str, dict | None] = {}
+        while len(ordered_teams) < len(self.configured_teams):
+            for team, attributes in self.configured_teams.items():
+                # Team already ordered
+                if team in ordered_teams:
+                    continue
+                # Team has parent, but parent not ordered yet
+                if parent := attributes.get("parent"):  # type: ignore
+                    if parent not in ordered_teams:
+                        continue
+                # Team has no parent, or parent already ordered
+                ordered_teams[team] = attributes
+        # Overwrite configured teams with ordered ones
+        self.configured_teams = ordered_teams
+
+    def create_missing_teams(self, dry: bool = False) -> None:
+        """Find out which teams are configured but not part of the org yet"""
 
         for team, attributes in self.configured_teams.items():
-            if team not in existent_team_names:
+            if team not in self.current_teams_str:
+                # If a parent team is configured, try to get its ID
                 if parent := attributes.get("parent"):  # type: ignore
-                    parent_id = self.org.get_team_by_slug(sluggify_teamname(parent)).id
+                    try:
+                        parent_id = self.org.get_team_by_slug(sluggify_teamname(parent)).id
+                    except UnknownObjectException:
+                        if dry:
+                            logging.debug(
+                                "For team %s, the configured parent team's ('%s') ID wasn't found, "
+                                "probably because it should be created but it's a dry-run. "
+                                "We set a default ID of 424242",
+                                team,
+                                parent,
+                            )
+                            parent_id = 424242
 
                     logging.info("Creating team '%s' with parent ID '%s'", team, parent_id)
                     self.stats.create_team(team)
@@ -310,6 +376,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                             privacy="closed",
                         )
 
+                # No parent team configured
                 else:
                     logging.info("Creating team '%s' without parent", team)
                     self.stats.create_team(team)
@@ -594,31 +661,38 @@ class GHorg:  # pylint: disable=too-many-instance-attributes, too-many-lines
                             team.name,
                         )
 
-    def get_unconfigured_teams(
+    def get_and_delete_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)
+                self.unconfigured_teams.append(team)
 
-        if unconfigured_teams:
+        if self.unconfigured_teams:
             if delete_unconfigured_teams:
-                for team in unconfigured_teams:
+                for team in self.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()
+                        try:
+                            team.delete()
+                        except UnknownObjectException as e:
+                            logging.info(
+                                "Team '%s' could not be deleted, probably because it was already "
+                                "deleted as part of a parent team. "
+                                "Error: %s",
+                                team.name,
+                                e,
+                            )
             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),
+                    ", ".join([team.name for team in self.unconfigured_teams]),
                 )
-                for team in unconfigured_teams:
+                for team in self.unconfigured_teams:
                     self.stats.delete_team(team=team.name, deleted=False)
 
     def get_members_without_team(

{github_org_manager-0.7.3 → github_org_manager-0.7.5}/gh_org_mgr/_helpers.py

@@ -34,7 +34,7 @@ def log_progress(message: str) -> None:
         sys.stderr.write("\r\033[K")
         sys.stderr.flush()
     else:
-        sys.stderr.write(f"\r\033[K⏳ {message}")
+        sys.stderr.write(f"\r\033[K⏳ {message}\n")
         sys.stderr.flush()
 
 

{github_org_manager-0.7.3 → github_org_manager-0.7.5}/gh_org_mgr/manage.py

@@ -134,6 +134,9 @@ def main():
         # Synchronise organisation owners
         log_progress("Synchronising organisation owners...")
         org.sync_org_owners(dry=args.dry, force=args.force)
+        # Validate parent/child team relationships
+        log_progress("Validating team hierarchy...")
+        org.ensure_team_hierarchy()
         # Create teams that aren't present at Github yet
         log_progress("Creating missing teams...")
         org.create_missing_teams(dry=args.dry)
@@ -145,7 +148,7 @@ def main():
         org.sync_teams_members(dry=args.dry)
         # Report and act on teams that are not configured locally
         log_progress("Checking for unconfigured teams...")
-        org.get_unconfigured_teams(
+        org.get_and_delete_unconfigured_teams(
             dry=args.dry,
             delete_unconfigured_teams=cfg_app.get("delete_unconfigured_teams", False),
         )
@@ -164,7 +167,6 @@ def main():
         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()
 

{github_org_manager-0.7.3 → github_org_manager-0.7.5}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "github-org-manager"
-version = "0.7.3"
+version = "0.7.5"
 description = "Manage a GitHub Organization, its teams, repository permissions, and more"
 authors = ["Max Mehl <max.mehl@deutschebahn.com>"]
 readme = "README.md"
@@ -27,19 +27,21 @@ gh-org-mgr = 'gh_org_mgr.manage:main'
 
 [tool.poetry.dependencies]
 python = "^3.10"
-pygithub = "^2.7.0"
-pyyaml = "^6.0.2"
-requests = "^2.32.4"
+pygithub = "^2.8.1"
+pyyaml = "^6.0.3"
+requests = "^2.32.5"
 python-slugify = "^8.0.4"
+jsonschema = "^4.25.1"
 
 [tool.poetry.group.dev.dependencies]
-black = "^25.1.0"
+black = "^25.9.0"
 isort = ">=5.13.2,<7.0.0"
-mypy = "^1.9.0"
-pylint = "^3.1.0"
-types-pyyaml = "^6.0.12.20240311"
-types-requests = "^2.32.0.20240712"
-bump-my-version = "^1.1.2"
+mypy = "^1.18.2"
+pylint = "^3.3.8"
+types-pyyaml = "^6.0.12.20250915"
+types-requests = "^2.32.4.20250913"
+bump-my-version = "^1.2.3"
+types-jsonschema = "^4.25.1.20250822"
 
 [build-system]
 requires = ["poetry-core"]