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.

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

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>

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.

Repository Guidelines

Repository Guidelines

Dos and Don’ts

Project Structure and Module Organization

Build, Test, and Development Commands

Coding Style and Naming Conventions

Testing Guidelines

Commit and Pull Request Guidelines

Safety and Permissions

Security and Configuration Tips

Related Skills

Nano Banana Pro

Markdown Converter

1password

Repository Guidelines

Dos and Don’ts

Project Structure and Module Organization

Build, Test, and Development Commands

Coding Style and Naming Conventions

Testing Guidelines

Commit and Pull Request Guidelines

Safety and Permissions

Security and Configuration Tips