feat: add restricted mode for reduced GitHub permissions (#2279)

docs/docs/installation/github.md

@@ -467,6 +467,7 @@ If you encounter rate limiting:
     pull-requests: write
     contents: write
   ```
+  If you cannot grant `contents: write`, set `config.restricted_mode = true` to gracefully skip operations that need elevated access (e.g., pushing changelog changes). See the [Restricted Mode guide](../usage-guide/additional_configurations.md#restricted-mode) for details.
 
 **Error: "Invalid JSON format"**
 

docs/docs/usage-guide/additional_configurations.md

@@ -280,3 +280,14 @@ ignore_ticket_labels = ["ignore-compliance", "skip-review", "wont-fix"]
 ```
 
 Where `ignore_ticket_labels` is a list of label names that should be ignored during ticket analysis.
+
+### Restricted Mode
+
+When running PR-Agent with limited GitHub/GitLab permissions (e.g., without `contents: write`), set `restricted_mode` to `true` to gracefully skip operations that require elevated access, like pushing changelog changes to the repository:
+
+```toml
+[config]
+restricted_mode = true
+```
+
+When enabled, any tool that needs code-push access (currently only `/update_changelog` with `push_changelog_changes=true`) will skip the operation and post a clear comment instead of failing with a 403 error. All other tools (`/review`, `/describe`, `/improve`, etc.) continue to work normally.

pr_agent/git_providers/bitbucket_provider.py

@@ -192,6 +192,8 @@ def is_supported(self, capability: str) -> bool:
         if capability in ['get_issue_comments', 'publish_inline_comments', 'get_labels', 'gfm_markdown',
                             'publish_file_comments']:
             return False
+        if capability == "push_code" and get_settings().config.restricted_mode:
+            return False
         return True
 
     def set_pr(self, pr_url: str):

pr_agent/git_providers/github_provider.py

@@ -84,6 +84,8 @@ def get_incremental_commits(self, incremental=IncrementalPR(False)):
             self._get_incremental_commits()
 
     def is_supported(self, capability: str) -> bool:
+        if capability == "push_code" and get_settings().config.restricted_mode:
+            return False
         return True
 
     def _get_owner_and_repo_path(self, given_url: str) -> str:

pr_agent/git_providers/gitlab_provider.py

@@ -290,6 +290,8 @@ def is_supported(self, capability: str) -> bool:
         if capability in ['get_issue_comments', 'create_inline_comment', 'publish_inline_comments',
             'publish_file_comments']: # gfm_markdown is supported in gitlab !
             return False
+        if capability == "push_code" and get_settings().config.restricted_mode:
+            return False
         return True
 
     def _get_project_path_from_pr_or_issue_url(self, pr_or_issue_url: str) -> str:

pr_agent/settings/configuration.toml

@@ -57,6 +57,7 @@ ignore_pr_authors = [] # authors to ignore from PR agent when an PR is created
 ignore_repositories = [] # a list of regular expressions of repository full names (e.g. "org/repo") to ignore from PR agent processing
 ignore_language_framework = [] # a list of code-generation languages or frameworks (e.g. 'protobuf', 'go_gen') whose auto-generated source files will be excluded from analysis
 #
+restricted_mode = false # when true, skip operations that require elevated permissions (e.g. pushing code to the repository)
 is_auto_command = false # will be auto-set to true if the command is triggered by an automation
 enable_ai_metadata = false # will enable adding ai metadata
 reasoning_effort = "medium" # "none", "minimal", "low", "medium", "high", "xhigh"

pr_agent/tools/pr_update_changelog.py

@@ -59,17 +59,25 @@ async def run(self):
         get_logger().debug("Relevant configs", artifacts=relevant_configs)
 
         # check if the git provider supports pushing changelog changes
-        if get_settings().pr_update_changelog.push_changelog_changes and not hasattr(
-            self.git_provider, "create_or_update_pr_file"
-        ):
-            get_logger().error(
-                "Pushing changelog changes is not currently supported for this code platform"
-            )
-            if get_settings().config.publish_output:
-                self.git_provider.publish_comment(
+        if get_settings().pr_update_changelog.push_changelog_changes:
+            if not hasattr(self.git_provider, "create_or_update_pr_file"):
+                get_logger().error(
                     "Pushing changelog changes is not currently supported for this code platform"
                 )
-            return
+                if get_settings().config.publish_output:
+                    self.git_provider.publish_comment(
+                        "Pushing changelog changes is not currently supported for this code platform"
+                    )
+                return
+            if not self.git_provider.is_supported("push_code"):
+                get_logger().error(
+                    "Pushing changelog changes is restricted by configuration"
+                )
+                if get_settings().config.publish_output:
+                    self.git_provider.publish_comment(
+                        "Pushing changelog changes is restricted by configuration"
+                    )
+                return
 
         if get_settings().config.publish_output:
             self.git_provider.publish_comment("Preparing changelog updates...", is_temporary=True)