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

* fix: scope ticket cache per-PR and fix Dynaconf list merge leaks in tests

- Cache key is now 'related_tickets_<md5(pr_url)>' instead of global
  'related_tickets', preventing stale tickets leaking between unrelated PRs
- Added cache_tickets=true config flag under [pr_reviewer] to allow disabling
- Fixed Dynaconf merge_enabled=True list append bug in both production code
  (env_bridge.py uses case-insensitive pop before set) and test helpers
  (restore_settings now calls _remove_key before every set)
- Added azure-identity dependency for Azure DevOps provider availability
- 1043 tests pass, 0 failures

* Revert "fix: scope ticket cache per-PR and fix Dynaconf list merge leaks in tests"

This reverts commit 7f0d154.

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

Add a `config.restricted_mode` option that gates operations requiring
elevated permissions (e.g. pushing code to the repository). When enabled,
`is_supported("push_code")` returns `False` on GitHub, GitLab, and
Bitbucket providers, and `/update_changelog --push_changelog_changes=true`
gracefully skips with a clear message instead of failing.

Users can set `restricted_mode = true` and use only `issues: write`
and `pull-requests: write` permissions, without `contents: write`.

* docs: document restricted_mode for reduced GitHub permissions

* docs: clarify minimal permissions for restricted mode

* fix: move restricted-mode check to __init__ to avoid unnecessary provider reads

PRUpdateChangelog.__init__() was fetching languages, files, and
CHANGELOG.md content before run() checked push_code support.
In restricted mode, these reads were wasted and could fail if
contents access is also restricted.

Move the capability check into __init__() before the expensive
provider calls, and store the result in self._skip_push so
run() can return early.

* fix: remove full-config logging from run() and use mock AI handler in test

- Remove relevant_configs logging that dumps full settings dicts
  (potential secret leak in logs)
- Pass ai_handler mock in test_run_without_push_support to avoid
  instantiating a real LiteLLMAIHandler

* fix: use spec'd mock for push-support test and fix docs permissions note

- Use MagicMock(spec=[...]) in test_run_without_push_support so
  hasattr() correctly returns False for missing attributes instead
  of brittle delattr on bare MagicMock
- Remove misleading 'contents: read (defaults to read)' comment
  from restricted mode docs; contents is simply not needed

* fix: skip __init__ provider reads when _skip_push is set

Move all provider-dependent initialization (vars dict, token handler,
ai_handler binding, language/file/changelog reads) behind the _skip_push
guard so the skip path avoids hitting the git provider at all during
construction.

* fix(update_changelog): degrade to comment instead of dropping output in restricted mode

Address Qodo review on #2491:

- #4 (skip path drops changelog output): when a changelog push is requested but not
  possible — provider lacks push support, or restricted_mode disables push_code — the
  tool no longer returns early with only an error. It now still generates the changelog
  and publishes it as a comment (which only needs pull-requests: write), with a note that
  the changes were not pushed. commit_changelog is set to False in that case.
- #5 (skip path still initializes): removes the special early-return init path; the normal
  flow builds only what's needed to generate the changelog.
- #6 (contents default note misleading): clarify that unlisted scopes default to none only
  within an explicit permissions: block; without one, defaults follow repo/org settings.

Update the "no push support" test to assert the comment fallback, and add a restricted_mode
test (push API present but is_supported('push_code') False) asserting it comments, not pushes.

* fix: generate changelog preview instead of silent skip when push is restricted

When restricted_mode is active and push_changelog_changes=true, the
tool now generates the changelog output via AI and publishes it as a
comment with a '(push restricted by configuration)' label, instead of
returning silently. This ensures users see the changelog even when
they don't have contents: write permissions.

For the 'not supported' case (provider lacks create_or_update_pr_file
entirely), the existing early-return behavior is preserved.

---------

Co-authored-by: Utsab <utsab@pr-agent.dev>
Co-authored-by: naorpeled <me@naor.dev>

Author: 3 people

docs/docs/installation/github.md

@@ -468,6 +468,13 @@ If you encounter rate limiting:
     pull-requests: write
     contents: write
   ```
+  If you cannot grant `contents: write`, set `config.restricted_mode = true` in your configuration. In that case you only need:
+  ```yaml
+  permissions:
+    issues: write
+    pull-requests: write
+  ```
+  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,24 @@ 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, set `restricted_mode` to `true` to gracefully skip operations that require elevated access (e.g., pushing changelog changes):
+
+```toml
+[config]
+restricted_mode = true
+```
+
+With restricted mode, the minimum workflow permissions are:
+
+```yaml
+permissions:
+  issues: write
+  pull-requests: write
+```
+
+Within an explicit `permissions:` block, any scope you do not list (such as `contents`) is set to `none`, so you do not need to grant `contents` — restricted mode skips every operation that would require `contents: write`. All tools (`/review`, `/describe`, `/improve`, etc.) continue to work normally with just `pull-requests: write`.
+
+> **Note:** this only holds when a `permissions:` block is present (as above). If you omit the `permissions:` block entirely, the effective defaults are governed by your repository/organization GitHub Actions settings and may grant broader access.

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

@@ -96,6 +96,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

@@ -23,14 +23,30 @@ class PRUpdateChangelog:
     def __init__(self, pr_url: str, cli_mode=False, args=None, ai_handler: partial[BaseAiHandler,] = LiteLLMAIHandler):
 
         self.git_provider = get_git_provider()(pr_url)
+
+        # Determine whether pushing the changelog to the repo is both requested and possible.
+        # If a push is requested but not possible — the provider has no push support, or
+        # restricted_mode disables the "push_code" capability — degrade gracefully: still
+        # generate the changelog and publish it as a comment (which only needs
+        # pull-requests: write) instead of skipping the tool and dropping the output entirely.
+        self.push_changelog_changes = get_settings().pr_update_changelog.push_changelog_changes
+        self.push_skipped_reason = None
+        if self.push_changelog_changes:
+            if not hasattr(self.git_provider, "create_or_update_pr_file"):
+                self.push_skipped_reason = "not supported for this git provider"
+            elif not self.git_provider.is_supported("push_code"):
+                self.push_skipped_reason = "restricted by configuration (restricted_mode)"
+        # Push only when it was requested AND is possible; otherwise fall back to a comment.
+        self.commit_changelog = self.push_changelog_changes and self.push_skipped_reason is None
+
         self.main_language = get_main_pr_language(
             self.git_provider.get_languages(), self.git_provider.get_files()
         )
-        self.commit_changelog = get_settings().pr_update_changelog.push_changelog_changes
         self._get_changelog_file()  # self.changelog_file_str
 
         self.ai_handler = ai_handler()
-        self.ai_handler.main_pr_language = self.main_language
+        if self.main_language:
+            self.ai_handler.main_pr_language = self.main_language
 
         self.patches_diff = None
         self.prediction = None
@@ -54,22 +70,15 @@ def __init__(self, pr_url: str, cli_mode=False, args=None, ai_handler: partial[B
 
     async def run(self):
         get_logger().info('Updating the changelog...')
-        relevant_configs = {'pr_update_changelog': dict(get_settings().pr_update_changelog),
-                            'config': dict(get_settings().config)}
-        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 a push was requested but isn't possible (unsupported provider or restricted_mode),
+        # the changelog is still generated and published as a comment below (commit_changelog is
+        # already False in that case), so the output is not dropped.
+        if self.push_skipped_reason:
+            get_logger().info(
+                f"Pushing changelog changes is {self.push_skipped_reason}; "
+                f"publishing the changelog as a comment instead"
             )
-            if get_settings().config.publish_output:
-                self.git_provider.publish_comment(
-                    "Pushing changelog changes is not currently supported for this code platform"
-                )
-            return
 
         if get_settings().config.publish_output:
             self.git_provider.publish_comment("Preparing changelog updates...", is_temporary=True)
@@ -89,7 +98,13 @@ async def run(self):
             if self.commit_changelog:
                 self._push_changelog_update(new_file_content, answer)
             else:
-                self.git_provider.publish_comment(f"**Changelog updates:** 🔄\n\n{answer}")
+                changelog_comment = f"**Changelog updates:** 🔄\n\n{answer}"
+                if self.push_skipped_reason:
+                    changelog_comment += (
+                        f"\n\n> ℹ️ These changes were not pushed to the repository "
+                        f"({self.push_skipped_reason})."
+                    )
+                self.git_provider.publish_comment(changelog_comment)
 
     async def _prepare_prediction(self, model: str):
         self.patches_diff = get_pr_diff(self.git_provider, self.token_handler, model)

tests/unittest/test_pr_update_changelog.py

@@ -138,23 +138,83 @@ def test_prepare_changelog_update_no_commit(self, changelog_tool):
         assert new_content == "## v1.1.0\n- New feature"
         assert "to commit the new content" in answer
 
+    def _make_no_push_provider(self, extra_spec=None):
+        spec = ["publish_comment", "remove_initial_comment", "get_pr_branch", "get_pr_description",
+                "get_commit_messages", "get_languages", "get_files", "get_pr_file_content",
+                "is_supported", "pr"]
+        if extra_spec:
+            spec += extra_spec
+        provider = MagicMock(spec=spec)
+        provider.pr = MagicMock()
+        provider.pr.title = "Test PR"
+        provider.get_pr_branch.return_value = "feature-branch"
+        provider.get_pr_description.return_value = "Test description"
+        provider.get_commit_messages.return_value = "fix: test commit"
+        provider.get_languages.return_value = {"Python": 80, "JavaScript": 20}
+        provider.get_files.return_value = ["test.py", "test.js"]
+        provider.get_pr_file_content.return_value = ""
+        return provider
+
     @pytest.mark.asyncio
-    async def test_run_without_push_support(self, changelog_tool, mock_git_provider):
-        """Test running changelog update when git provider doesn't support pushing."""
-        # Arrange
-        delattr(mock_git_provider, 'create_or_update_pr_file')  # Remove the method
-        changelog_tool.commit_changelog = True
-        
-        with patch('pr_agent.tools.pr_update_changelog.get_settings') as mock_settings:
+    async def test_run_without_push_support(self, mock_ai_handler):
+        """When the provider can't push (no create_or_update_pr_file), the changelog must still
+        be generated and published as a comment (graceful degradation), not dropped entirely."""
+        provider = self._make_no_push_provider()  # spec omits create_or_update_pr_file
+        provider.is_supported.return_value = True
+
+        with patch('pr_agent.tools.pr_update_changelog.get_git_provider', return_value=lambda url: provider), \
+             patch('pr_agent.tools.pr_update_changelog.get_main_pr_language', return_value="Python"), \
+             patch('pr_agent.tools.pr_update_changelog.retry_with_fallback_models'), \
+             patch('pr_agent.tools.pr_update_changelog.get_settings') as mock_settings:
             mock_settings.return_value.pr_update_changelog.push_changelog_changes = True
             mock_settings.return_value.config.publish_output = True
-            
-            # Act
-            await changelog_tool.run()
-            
-            # Assert
-            mock_git_provider.publish_comment.assert_called_once()
-            assert "not currently supported" in str(mock_git_provider.publish_comment.call_args)
+            mock_settings.return_value.pr_update_changelog.extra_instructions = ""
+            mock_settings.return_value.pr_update_changelog_prompt.system = ""
+            mock_settings.return_value.pr_update_changelog_prompt.user = ""
+            mock_settings.return_value.get.return_value = {}
+            tool = PRUpdateChangelog("https://example.com/pr/123", ai_handler=lambda: mock_ai_handler)
+
+            # Push isn't possible -> degrade to comment mode (don't push, don't drop the output).
+            assert tool.push_skipped_reason == "not supported for this git provider"
+            assert tool.commit_changelog is False
+
+            tool.prediction = "## v1.1.0\n- New feature"
+            await tool.run()
+
+            published = " ".join(str(c) for c in provider.publish_comment.call_args_list)
+            assert "Changelog updates" in published  # the generated changelog was posted
+            assert "not pushed" in published          # with a note it wasn't committed
+
+    @pytest.mark.asyncio
+    async def test_run_restricted_mode_publishes_comment_instead_of_pushing(self, mock_ai_handler):
+        """restricted_mode: the provider supports the push API, but is_supported('push_code') is
+        False, so the changelog must be published as a comment rather than pushed to the repo."""
+        provider = self._make_no_push_provider(extra_spec=["create_or_update_pr_file"])
+        provider.is_supported.return_value = False  # restricted_mode disables push_code
+
+        with patch('pr_agent.tools.pr_update_changelog.get_git_provider', return_value=lambda url: provider), \
+             patch('pr_agent.tools.pr_update_changelog.get_main_pr_language', return_value="Python"), \
+             patch('pr_agent.tools.pr_update_changelog.retry_with_fallback_models'), \
+             patch('pr_agent.tools.pr_update_changelog.get_settings') as mock_settings:
+            mock_settings.return_value.pr_update_changelog.push_changelog_changes = True
+            mock_settings.return_value.config.publish_output = True
+            mock_settings.return_value.pr_update_changelog.extra_instructions = ""
+            mock_settings.return_value.pr_update_changelog_prompt.system = ""
+            mock_settings.return_value.pr_update_changelog_prompt.user = ""
+            mock_settings.return_value.get.return_value = {}
+            tool = PRUpdateChangelog("https://example.com/pr/1", ai_handler=lambda: mock_ai_handler)
+
+            assert tool.push_skipped_reason == "restricted by configuration (restricted_mode)"
+            assert tool.commit_changelog is False
+            provider.is_supported.assert_called_with("push_code")
+
+            tool.prediction = "## v1.1.0\n- feat"
+            await tool.run()
+
+            provider.create_or_update_pr_file.assert_not_called()  # never pushed
+            published = " ".join(str(c) for c in provider.publish_comment.call_args_list)
+            assert "Changelog updates" in published
+            assert "not pushed" in published
 
     @pytest.mark.asyncio
     async def test_run_with_push_support(self, changelog_tool, mock_git_provider):