feat: add immutable release support for repositories and org settings (#663)

  Manage GitHub immutable release settings at both repository and
  organization level, including selected repository enforcement.
  Coerce repo settings against org policy during diff/apply and add
  schema, docs and test updates for the new configuration fields.

Signed-off-by: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com>

Author: dcalavrezo-qorix

docs/reference/organization/repository/index.md

@@ -46,6 +46,7 @@ Definition of a Repository for a GitHub organization, the following properties a
 | _template_repository_                     | string or null                                            | The template repository to use when creating the repo                                   | read-only, only considered during creation                                                                                                                                                 |
 | _forked_repository_                       | string or null                                            | The repository to fork when creating the repo                                           | only considered during creation                                                                                                                                                            |
 | _fork_default_branch_only_                | boolean                                                   | When creating a fork, whether only the default branch will be included in the fork      | only considered during creation                                                                                                                                                            |
+| _immutable_releases_enabled_              | boolean                                                   | If immutable releases are enabled for this repository                                   | Can be overridden by organization-level immutable release settings                                                                                                                          |
 | _web_commit_signoff_required_             | boolean                                                   | If the repo requires web commit signoff                                                 |                                                                                                                                                                                            |
 | _workflows_                               | [Workflow Settings](#workflow-settings)                   | Workflow settings on organizational level                                               |                                                                                                                                                                                            |
 | _webhooks_                                | list\[[Webhook](webhook.md)\]                             | webhooks defined for this repo, see section above for details                           |                                                                                                                                                                                            |

docs/reference/organization/settings.md

@@ -14,6 +14,8 @@ The following table captures all supported settings on organization level:
 | _default_branch_name_                           | string                                       | The default branch name for newly created repositories                                                                                                                         |                                                          |
 | _default_repository_permission_                 | string                                       | The base permission for all members of the organization for its repositories                                                                                                   | `none`, `read`, `write` or `admin`                       |
 | _default_code_security_configurations_disabled_ | boolean                                      | If default code security configuration should be disabled, no processing if the setting is set to `true`                                                                       |                                                          |
+| _immutable_releases_enforced_repositories_      | string                                       | Defines which repositories must use immutable releases                                                                                                                          | `all`, `none` or `selected`                              |
+| _immutable_releases_selected_repositories_      | list[string]                                 | The list of repositories for which immutable releases are enforced                                                                                                              | Only taken into account when `immutable_releases_enforced_repositories` is set to `selected` |
 | _discussion_source_repository_                  | string or null                               | The source repository to host organization discussions                                                                                                                         |                                                          |
 | _has_discussions_                               | boolean                                      | If discussions are enabled for the organization. If `true`, property `discussion_source_repository` must be set as well                                                        |                                                          |
 | _has_organization_projects_                     | boolean                                      | If the organization can have organization projects                                                                                                                             |                                                          |
@@ -58,6 +60,7 @@ The following table captures all supported settings on organization level:
 - enabling either `dependabot_alerts_enabled_for_new_repositories` or `dependabot_security_updates_enabled_for_new_repositories` also requires enabling `dependency_graph_enabled_for_new_repositories`
 - enabling `dependabot_security_updates_enabled_for_new_repositories` also requires enabling `dependabot_alerts_enabled_for_new_repositories`
 - enabling `has_discussions` also requires setting `discussion_source_repository` to a valid repository to host the discussions
+- specifying a non-empty list of `immutable_releases_selected_repositories` while `immutable_releases_enforced_repositories` is not set to `selected`, triggers a warning
 - specifying a non-empty list of `selected_repositories` while `enabled_repositories` is not set to `selected`, triggers a warning
 - specifying a non-empty list of `allow_action_patterns` while `allowed_actions` is not set to `selected`, triggers a warning
 

docs/userguide/unsupported.md

@@ -2,7 +2,7 @@ Not all features or settings of a GitHub organization and its associated resourc
 by the means of `otterdog`. The following non-exhaustive list outlines settings that are currently not supported:
 
 - setting the profile picture of an organization or a social media preview for a repository [#119](https://github.com/eclipse-csi/otterdog/issues/119)
-- manage items that should be visible on the main page, i.e. releases, packages, deployments
+- manage release entries, packages, or deployments that should be visible on the main page
 - manage default repository labels on organization level
 - secrets and variables for codespaces and dependabot
 - managing GitHub apps or oauth policies

otterdog/models/organization_settings.py

@@ -68,6 +68,8 @@ class OrganizationSettings(ModelObject):
     two_factor_requirement: bool = dataclasses.field(metadata={"read_only": True})
     web_commit_signoff_required: bool
     default_code_security_configurations_disabled: bool
+    immutable_releases_enforced_repositories: str
+    immutable_releases_selected_repositories: list[str]
     members_can_create_private_repositories: bool
     members_can_create_public_repositories: bool
     members_can_fork_private_repositories: bool
@@ -92,6 +94,9 @@ def model_object_name(self) -> str:
         return "settings"
 
     def include_field_for_diff_computation(self, field: dataclasses.Field) -> bool:
+        if field.name == "immutable_releases_selected_repositories":
+            return self.immutable_releases_enforced_repositories == "selected"
+
         if self.has_discussions is False and field.name == "discussion_source_repository":
             return False
 
@@ -128,6 +133,28 @@ def validate(self, context: ValidationContext, parent_object: Any) -> None:
                 "enabling 'members_can_create_private_pages' requires an 'enterprise' plan.",
             )
 
+        if is_set_and_valid(self.immutable_releases_enforced_repositories):
+            if self.immutable_releases_enforced_repositories not in {"all", "none", "selected"}:
+                context.add_failure(
+                    FailureType.ERROR,
+                    f"'immutable_releases_enforced_repositories' has value "
+                    f"'{self.immutable_releases_enforced_repositories}', "
+                    f"while only values ('all' | 'none' | 'selected') are allowed.",
+                )
+
+            if (
+                self.immutable_releases_enforced_repositories != "selected"
+                and is_set_and_valid(self.immutable_releases_selected_repositories)
+                and len(self.immutable_releases_selected_repositories) > 0
+            ):
+                context.add_failure(
+                    FailureType.WARNING,
+                    f"'immutable_releases_enforced_repositories' is set to "
+                    f"'{self.immutable_releases_enforced_repositories}', "
+                    f"but 'immutable_releases_selected_repositories' is set to "
+                    f"'{self.immutable_releases_selected_repositories}', setting will be ignored.",
+                )
+
         if is_set_and_valid(self.default_repository_permission):
             if self.default_repository_permission not in {
                 "none",

otterdog/models/repository.py

@@ -86,6 +86,7 @@ class Repository(ModelObject):
     archived: bool
     allow_forking: bool
     web_commit_signoff_required: bool
+    immutable_releases_enabled: bool
     secret_scanning: str
     secret_scanning_push_protection: str
     dependabot_alerts_enabled: bool
@@ -281,6 +282,9 @@ def coerce_from_org_settings(self, org_settings: OrganizationSettings, for_patch
         if org_settings.plan != "enterprise":
             copy.gh_pages_visibility = UNSET  # type: ignore
 
+        if self._org_enforces_immutable_releases(org_settings):
+            copy.immutable_releases_enabled = UNSET  # type: ignore
+
         if is_set_and_present(self.custom_properties):
             for custom_property in org_settings.custom_properties:
                 current_property_value = self.custom_properties.get(custom_property.name, None)
@@ -303,6 +307,16 @@ def coerce_from_org_settings(self, org_settings: OrganizationSettings, for_patch
 
         return copy
 
+    def _org_enforces_immutable_releases(self, org_settings: OrganizationSettings) -> bool:
+        if org_settings.immutable_releases_enforced_repositories == "all":
+            return True
+
+        return (
+            org_settings.immutable_releases_enforced_repositories == "selected"
+            and is_set_and_valid(org_settings.immutable_releases_selected_repositories)
+            and self.name in org_settings.immutable_releases_selected_repositories
+        )
+
     def requires_language_validation(self) -> bool:
         return (
             self.code_scanning_default_setup_enabled is True
@@ -356,7 +370,8 @@ async def validate_code_scanning_languages(self, context: ValidationContext, par
                         context.add_failure(
                             FailureType.ERROR,
                             f"{self.get_model_header(parent_object)} has 'code_scanning_default_languages' "
-                            f"configured with '{configured_language}' but this language is not detected in the repository. "
+                            f"configured with '{configured_language}' but this language is not detected "
+                            f"in the repository. "
                             f"Detected languages: {', '.join(sorted(languages.keys()))}",
                         )
             except Exception as e:
@@ -454,6 +469,13 @@ def validate(self, context: ValidationContext, parent_object: Any) -> None:
                 f"the organization requires it, setting will be ignored.",
             )
 
+        if self.immutable_releases_enabled is False and self._org_enforces_immutable_releases(org_settings):
+            context.add_failure(
+                FailureType.INFO,
+                f"{self.get_model_header()} has 'immutable_releases_enabled' disabled, while "
+                f"the organization enforces immutable releases for this repository, setting will be ignored.",
+            )
+
         secret_scanning_disabled = self.secret_scanning == "disabled"
         secret_scanning_push_protection_enabled = self.secret_scanning_push_protection == "enabled"
         if secret_scanning_disabled and secret_scanning_push_protection_enabled and self.archived is False:
@@ -901,6 +923,7 @@ def transform_perm(permissions):
                 "branch_protection_rules": K([]),
                 "rulesets": K([]),
                 "environments": K([]),
+                "immutable_releases_enabled": OptionalS("immutable_releases_enabled", default=UNSET),
                 "secret_scanning": OptionalS("security_and_analysis", "secret_scanning", "status", default=UNSET),
                 "secret_scanning_push_protection": OptionalS(
                     "security_and_analysis",
@@ -1210,6 +1233,7 @@ def generate_live_patch(
         if current_object is None:
             handler(LivePatch.of_addition(coerced_object, parent_object, coerced_object.apply_live_patch))
         else:
+            raw_current_object = current_object
             if context.current_org_settings is not None:
                 current_org_settings = cast("OrganizationSettings", context.current_org_settings)
                 current_object = current_object.coerce_from_org_settings(current_org_settings)
@@ -1237,6 +1261,19 @@ def generate_live_patch(
                     if k not in to_value:
                         change.to_value[k] = None
 
+            if (
+                context.current_org_settings is not None
+                and raw_current_object._org_enforces_immutable_releases(
+                    cast("OrganizationSettings", context.current_org_settings)
+                )
+                and not expected_object._org_enforces_immutable_releases(expected_org_settings)
+                and is_set_and_valid(coerced_object.immutable_releases_enabled)
+            ):
+                modified_repo["immutable_releases_enabled"] = Change(
+                    raw_current_object.immutable_releases_enabled,
+                    coerced_object.immutable_releases_enabled,
+                )
+
             if len(modified_repo) > 0:
                 if "archived" in modified_repo:
                     change = modified_repo["archived"]