Merge 9f08ab29e1 into ede3f82143

This will make future contributions and development with the help of AI
Agents easier.

It is primarily generated by codex-cli v0.40.0 using gpt-5-codex-high,
along with the following AGENTS.md construction prompt:
- https://gist.github.com/PeterDaveHello/f30c38a156982a35683edfd5ece2d474

Reference:
- https://agents.md/

AGENTS.md

@@ -0,0 +1,70 @@
+# Repository Guidelines
+
+## Dos and Don’ts
+
+- **Do** match the interpreter requirement declared in `pyproject.toml` (Python ≥ 3.12) and install `requirements.txt` plus `requirements-dev.txt` before running tools.
+- **Do** run tests with `PYTHONPATH=.` set to keep imports functional (for example `PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test_fix_json_escape_char.py -q`).
+- **Do** adjust configuration through `.pr_agent.toml` or files under `pr_agent/settings/` instead of hard-coding values.
+- **Don’t** commit secrets or access tokens; rely on environment variables as shown in the health and e2e tests.
+- **Don’t** reformat or reorder files globally; match existing 120-character lines, import ordering, and docstring style.
+- **Don’t** delete or rename configuration, prompt, or workflow files without maintainer approval.
+
+## Project Structure and Module Organization
+
+PR-Agent automates AI-assisted reviews for pull requests across multiple git providers.
+
+- `pr_agent/agent/` orchestrates commands (`review`, `describe`, `improve`, etc.) via `pr_agent/agent/pr_agent.py`.
+- `pr_agent/tools/` implements individual capabilities such as reviewers, code suggestions, docs updates, and label generation.
+- `pr_agent/git_providers/` and `pr_agent/identity_providers/` handle integrations with GitHub, GitLab, Bitbucket, Azure DevOps, and secrets.
+- `pr_agent/settings/` stores Dynaconf defaults (prompts, configuration templates, ignore lists) respected at runtime; `.pr_agent.toml` overrides repository-level behavior.
+- `tests/unittest/`, `tests/e2e_tests/`, and `tests/health_test/` contain pytest-based unit, end-to-end, and smoke checks.
+- `docs/` holds the MkDocs site (`docs/mkdocs.yml` plus content under `docs/docs/`); overrides live in `docs/overrides/`.
+- `.github/workflows/` defines CI pipelines for unit tests, coverage, docs deployment, pre-commit, and PR-agent self-review.
+- `docker/` and the root Dockerfiles provide build targets for services (`github_app`, `gitlab_webhook`, etc.) and the `test` stage used in CI.
+
+## Build, Test, and Development Commands
+
+- Create or activate a virtual environment, then install runtime dependencies with `pip install -r requirements.txt`; add development tooling via `pip install -r requirements-dev.txt`.
+- Run a single unit test (verified): `PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test_fix_json_escape_char.py -q`.
+- Run the full unit suite: `PYTHONPATH=. ./.venv/bin/pytest tests/unittest -v`.
+- Execute the CLI locally once dependencies and API keys are available: `python -m pr_agent.cli --pr_url <https://host/org/repo/pull/123> review`.
+- Build the test Docker target mirror of CI when containerizing: `docker build -f docker/Dockerfile --target test .` (loads dev dependencies and copies `tests/`).
+- Generate and deploy documentation with MkDocs after installing the same extras as CI (`mkdocs-material`, `mkdocs-glightbox`): `mkdocs serve -f docs/mkdocs.yml` for previews and `mkdocs gh-deploy -f docs/mkdocs.yml` for publication.
+
+## Coding Style and Naming Conventions
+
+- Python sources follow the Ruff configuration in `pyproject.toml` (`line-length = 120`, Pyflakes plus `flake8-bugbear` checks, and isort ordering). Keep imports grouped as isort would produce and prefer double quotes for strings.
+- Pre-commit (`.pre-commit-config.yaml`) enforces trailing whitespace cleanup, final newlines, TOML/YAML validity, and optional `isort`; run `pre-commit run --all-files` before submitting patches if installed.
+- Match existing docstring and comment style—concise English comments using imperative phrasing only where necessary.
+- Configuration files in `pr_agent/settings/` are TOML; preserve formatting, section order, and comments when editing prompts or defaults.
+- Markdown in `docs/` uses MkDocs conventions (YAML front matter absent; rely on heading hierarchy already in place).
+
+## Testing Guidelines
+
+- Pytest is the standard framework; keep new tests under the closest matching directory (`tests/unittest/` for unit logic, `tests/e2e_tests/` for integration flows, `tests/health_test/` for smoke coverage).
+- Prefer focused unit tests that isolate helpers in `pr_agent/algo/`, `pr_agent/tools/`, or provider adapters; use parameterized tests where existing files already do so.
+- Set `PYTHONPATH=.` when invoking pytest from the repository root to avoid import errors.
+- End-to-end suites require provider tokens (`TOKEN_GITHUB`, `TOKEN_GITLAB`, `BITBUCKET_USERNAME`, `BITBUCKET_PASSWORD`) and may take several minutes; run them only when credentials and sandboxes are configured.
+- The health test (`tests/health_test/main.py`) exercises `/describe`, `/review`, and `/improve`; update expected artifacts if prompts change meaningfully.
+
+## Commit and Pull Request Guidelines
+
+- Follow `CONTRIBUTING.md`: keep changes focused, add or update tests, and use Conventional Commit-style messages (e.g., `fix: handle missing repo settings gracefully`).
+- Target branch names follow `feature/<name>` or `fix/<issue>` patterns for substantial work.
+- Reference related issues and update README or docs when user-facing behavior shifts.
+- Ensure CI workflows (`build-and-test`, `code-coverage`, `docs-ci`) succeed locally or in draft PRs before requesting review; reproduce failures with the documented commands above.
+- Include screenshots or terminal captures when modifying user-visible output or documentation previews.
+
+## Safety and Permissions
+
+- Ask for confirmation before adding dependencies, renaming files, or changing workflow definitions; many consumers embed these paths and prompts.
+- Stay within existing formatting and directory conventions—avoid mass refactors, re-sorting of prompts, or reformatting Markdown beyond the touched sections.
+- You may read files, list directories, and run targeted lint/test/doc commands without prior approval; coordinate before launching full Docker builds or e2e suites that rely on external credentials.
+- Never commit cached credentials, API keys, or coverage artifacts; CI already handles secrets through GitHub Actions.
+- Treat prompt and configuration files as single sources of truth—update mirrors (`.pr_agent.toml`, `pr_agent/settings/*.toml`) together when behavior changes.
+
+## Security and Configuration Tips
+
+- Secrets should be supplied through environment variables (see usages in `tests/e2e_tests/test_github_app.py` and `tests/health_test/main.py`); do not persist them in code or configuration files.
+- Adjust runtime behavior by overriding keys in `.pr_agent.toml` or by supplying repository-specific Dynaconf files; keep overrides minimal and documented inside the PR description.
+- Review `SECURITY.md` before disclosing vulnerabilities and follow its contact instructions for responsible reporting.

docs/docs/usage-guide/configuration_options.md

@@ -58,7 +58,7 @@ Then you can give a list of extra instructions to the `review` tool.
 
 ## Global configuration file 💎
 
-`Platforms supported: GitHub, GitLab, Bitbucket`
+`Platforms supported: GitHub, GitLab (cloud), Bitbucket (cloud)`
 
 If you create a repo called `pr-agent-settings` in your **organization**, its configuration file `.pr_agent.toml` will be used as a global configuration file for any other repo that belongs to the same organization.
 Parameters from a local `.pr_agent.toml` file, in a specific repo, will override the global configuration parameters.
@@ -69,18 +69,21 @@ For example, in the GitHub organization `Codium-ai`:
 
 - The repo [`https://github.com/Codium-ai/pr-agent`](https://github.com/Codium-ai/pr-agent/blob/main/.pr_agent.toml) inherits the global configuration file from `pr-agent-settings`.
 
-### Bitbucket Organization level configuration file 💎
+## Project/Group level configuration file 💎
+
+`Platforms supported: GitLab, Bitbucket Data Center`
+
+Create a repository named `pr-agent-settings` within a specific project (Bitbucket) or a group/subgroup (Gitlab). 
+The configuration file in this repository will apply to all repositories directly under the same project/group/subgroup.
+
+!!! note "Note"
+    For Gitlab, in case of a repository nested in several sub groups, the lookup for a pr-agent-settings repo will be only on one level above such repository.
+
+
+## Organization level configuration file 💎
 
 `Relevant platforms: Bitbucket Data Center`
 
-In Bitbucket Data Center, there are two levels where you can define a global configuration file:
-
-- Project-level global configuration:
-
-Create a repository named `pr-agent-settings` within a specific project. The configuration file in this repository will apply to all repositories under the same project.
-
-- Organization-level global configuration:
-
 Create a dedicated project to hold a global configuration file that affects all repositories across all projects in your organization.
 
 **Setting up organization-level global configuration:**