A lightweight Python utility for retrieving and fixing SonarQube/SonarCloud code quality violations (bugs, vulnerabilities, code smells) from any branch.
pyopenfixer connects to your SonarQube server, discovers the main branch, and fetches all open/confirmed violations using the SonarQube Issues API with automatic pagination. The violations are returned as a list of dictionaries, making them easy to filter, transform, or export.
The tool's behavior depends on which git branch you're currently on:
- On the main branch — fetches and prints every open violation on main, a severity summary, and the branch's code coverage percentage.
- On any other branch — fetches violations for both the current branch and main, then reports only the violations that are new to the current branch (i.e. not already present on main), along with coverage for both branches.
You may also pass in a SonarQube rule (e.g. python:S1234) and pyopenfixer will use opencode to attempt to fix all the violations for that rule.
- Automatic branch discovery — Queries the SonarCloud Issues API to find the main branch instead of hardcoding a branch name
- Full pagination support — Handles projects with thousands of issues
- Three issue types — Fetches
BUG,VULNERABILITY, andCODE_SMELLissues - Filterable results — All fields from the SonarCloud Issue object are preserved (severity, rule, line, message, status, assignee, etc.)
- Importable — The
main()function returns violations as a list, so you can import it into other scripts - Branch-aware diffing — On non-main branches, reports only violations that are new relative to main instead of the full list
- Coverage reporting — Fetches and prints the code coverage percentage for each branch checked
- Minimal dependencies — Only requires the
requestslibrary; the optional auto-fix feature additionally shells out to theopencodeCLI if it's installed - CI/CD integration — Automatic SonarCloud analysis on every push and merge via GitHub Actions
If you encounter an error like: "Invalid directory path in 'source' element: /home/runner/work/pyopenfixer/pyopenfixer", it's typically a configuration issue in your CI/CD setup or SonarQube configuration.
Ensure that:
- You are running coverage analysis with the correct path configuration
- The coverage report paths in sonar-project.properties match your current working directory
- If running locally, ensure you're generating coverage data in a directory that matches your SonarQube configuration
- Python 3.10+ (uses dictionary type hints with
list[dict]) requestslibrarySONAR_TOKENenvironment variable set to your SonarCloud user token withread_issuespermission- You may need a free SonarCloud account (https://sonarcloud.io)
opencodeCLI installed and available on yourPATH— only required if you use the rule auto-fix feature; without it, fixing is skipped with a warning
Dependencies are pinned in pyproject.toml/uv.lock, with a hash-locked requirements.txt mirror used by CI. Pick one:
Using uv (recommended — installs requests plus the pinned test extras):
uv sync --extra testUsing pip with the hash-locked requirements file (matches CI exactly):
pip install --require-hashes -r requirements.txtMinimal, unpinned install:
pip install requestsCreate (or edit) config.json at the project root:
{
"sonarqube_url": "https://sonarcloud.io",
"project_key": "my-organization:my-project"
}| Field | Description | Required |
|---|---|---|
sonarqube_url |
Base URL of your SonarCloud/SonarQube instance (no trailing slash needed) | Yes |
project_key |
The exact project key as shown in SonarCloud/SonarQube (e.g., org:project) |
Yes |
The token is loaded from the SONAR_TOKEN environment variable — it is not stored in any file.
- Log in to SonarCloud (https://sonarcloud.io)
- Click your avatar —> My Account —> Security
- Click Generate Token
- Name it (e.g.,
pyopenfixer) - Leave scopes at default (read-only access to issues is enough)
- Copy the token
Once you have your token, set the SONAR_TOKEN environment variable:
export SONAR_TOKEN="sqp_a1b2c3d4e5f6g7h8i9j0"On Windows:
set SONAR_TOKEN=sqp_a1b2c3d4e5f6g7h8i9j0In CI/CD pipelines, set SONAR_TOKEN as a secret environment variable in your pipeline settings.
The repository includes a GitHub Actions workflow (.github/workflows/sonarcloud.yml) that automatically analyzes the project in SonarCloud on every push and pull request. To enable it:
- Create a SonarCloud project (if not already created) at https://sonarcloud.io/dashboard
- Copy the Project Key and Organisation Key
- Add them to your
config.json - Navigate to your repository on GitHub.com
- Go to Settings —> Secrets and variables —> Actions
- Click New repository secret
- Name the secret
SONAR_TOKENand paste the token you generated above - Commit your changes
The workflow will trigger on:
pushto branchesmain,master, ordeveloppull_requestof any type (opened,synchronize,reopened)
Each workflow run will:
- Checkout the repository with full history
- Set up Python 3.14
- Install dependencies
- Run the test suite
- Trigger a SonarCloud scan using the official
SonarSource/sonarcloud-github-action@v3
No additional configuration is required.
python sonar_violations.pymain() reads the rule to fix from the second command-line argument (sys.argv[2]) — the first argument is currently unused, so any placeholder value must be passed in that position before the rule. Once given a rule, it filters violations to that rule and automatically runs opencode run on each match:
python sonar_violations.py _ java:S1858This will:
- Fetch all violations from the project and branch
- Filter to only violations with
rule == "java:S1858" - For each matching violation, run:
opencode run "fix the problem {message} in {component} on line {line}"
The opencode command receives a prompt built from the violation's message, component, and line fields, allowing AI to automatically remediate the issue. If opencode isn't on your PATH, each fix attempt is skipped with a warning instead of failing.
python sonar_violations.py _ python:S301Output on the main branch:
current git branch: main
main branch: main
on main branch - 142 violations from my-company:my-project on branch 'main':
[MAJOR] BUG - src/utils.py (python:S125) at line 42: Variable name "x" is too short
[CRITICAL] VULNERABILITY - src/auth.py (python:S2009) at line 101: "os.system" is a security risk
...
Severity summary:
BLOCKER: 3
CRITICAL: 5
MAJOR: 12
MINOR: 47
INFO: 75
Total violations on 'main': 142
Code coverage summary for main: 82.4
Thank you for pushing PyOpenFixer 1.0.3! Please consider starring the project on GitHub: https://github.com/larrydiamond/pyopenfixer
Output on a feature branch (only violations new relative to main are shown):
current git branch: feature/my-branch
main branch: main
on branch 'feature/my-branch' (not 'main'):
Total violations on 'feature/my-branch': 5
Total violations on 'main': 142
New violations on 'feature/my-branch' that are not found on 'main': 2
New violations on 'feature/my-branch' not in 'main':
[MAJOR] BUG - src/new_feature.py (python:S125) at line 10: Variable name "x" is too short
[MINOR] CODE_SMELL - src/new_feature.py (python:S1481) at line 22: Remove this unused local variable "tmp"
Severity summary:
MAJOR: 1
MINOR: 1
Code coverage summary for feature/my-branch: 78.1
Code coverage summary for main: 82.4
Thank you for pushing PyOpenFixer 1.0.3! Please consider starring the project on GitHub: https://github.com/larrydiamond/pyopenfixer
Note: If main has violations but your current branch reports zero, pyopenfixer prints a note that this can happen on free installations of SonarQube or free SonarCloud accounts, which may not run analysis on non-main branches.
from sonar_violations import main
violations = main()
# Filter by severity
critical = [v for v in violations if v.get("severity") == "CRITICAL"]
# Filter by type
vulnerabilities = [v for v in violations if v.get("type") == "VULNERABILITY"]
# Export to CSV or JSON
import json
with open("violations.json", "w") as f:
json.dump(violations, f, indent=2)from sonar_violations import fetch_violations, get_main_branch_name
import os
import requests
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {os.environ['SONAR_TOKEN']}"})
branch = get_main_branch_name(session, "https://sonarcloud.io", "my-key")
violations = fetch_violations(session, "https://sonarcloud.io", "my-key", branch)The violations list contains one dictionary per SonarQube issue. Each dictionary includes all fields from the SonarQube API response, such as:
| Field | Example Value | Description |
|---|---|---|
key |
"AAAABCDe12345" |
Unique issue ID |
rule |
"python:S125" |
SonarQube rule identifier |
severity |
"MAJOR" |
Severity: INFO, MINOR, MAJOR, CRITICAL, BLOCKER |
type |
"BUG" |
Issue type: BUG, VULNERABILITY, CODE_SMELL |
message |
"Replace this use of 'eval'." |
Rule description / violation message |
component |
"src/auth.py" |
Source file path |
line |
47 |
Line number where issue is detected |
status |
"OPEN" |
Issue status: OPEN, CONFIRMED, REOPENED, CLOSED, ACCEPTED |
assignee |
"jdoe" |
Assigned developer |
author |
"jdoe" |
Who created the issue |
tags |
["cert", "cwe-79"] |
Rule tags (CWE, OWASP, etc.) |
creationDate |
"2024-01-15T10:30:00+0000" |
When the issue was created |
updateDate |
"2024-03-20T14:00:00+0000" |
When the issue was last updated |
effort |
"30min" |
Suggested fix effort |
comments |
[...] |
List of comments on the issue |
attachments |
[...] |
Attached screenshots/documents |
See the SonarQube Issues API docs for the full schema.
├── .github/workflows/sonarcloud.yml # GitHub Actions CI/CD
├── config.json.example # Sample configuration (safe to commit)
├── config.json # Your actual config (gitignored — contains your token)
├── sonar_violations.py # Main application logic
├── pyproject.toml # Project metadata and pinned dependencies
├── uv.lock # Full resolved dependency lock (uv)
├── requirements.in # Top-level dependency names (source for pip-compile/uv)
├── requirements.txt # Hash-locked dependencies used by CI
├── requirements.locked.txt # Hash-locked dependencies (with extras)
├── sonar-project.properties # SonarCloud/SonarQube scanner configuration
├── tests/ # Unit tests (pytest)
│ └── test_sonar_violations.py
├── .gitignore # Prevents committing secrets
├── README.md # This file
└── AGENTS.md # Instructions for AI coding agents
Tests are written using pytest and can be run from the project root. If you installed with uv sync --extra test (see Setup), pytest is already available in .venv; otherwise:
pip install pytest
pytestTo run with verbose output:
pytest -vTo run a specific test class or file:
pytest tests/test_sonar_violations.py -vTo run a specific test method:
pytest tests/test_sonar_violations.py::TestLoadConfig::test_loads_valid_config -vTo see coverage:
pip install pytest-cov
pytest --cov=sonar_violations --cov-report=term-missingThe test suite covers:
TestLoadConfig(6 tests) — valid config, default path, missing file, missing keys, invalid JSONTestGetCurrentBranch(5 tests) — normal branch, empty output, CalledProcessError, FileNotFoundError, custom cwdTestIsBranchMain(3 tests) — matching branches, non-matching, case sensitivityTestGetMainBranchName(3 tests) — returns main branch, fallback to "main", HTTP errorsTestFetchViolations(5 tests) — single page, multi-page pagination, empty list, correct params, HTTP errorsTestViolationSortKey(6 tests) — type ordering, severity ordering, unknown types/severities, rule/line tiebreakersTestMain(3 tests) — missing token, successful run, skipping output on non-main branch
| Endpoint | Purpose |
|---|---|
GET /api/project_branches/list |
Discover main branch name |
GET /api/issues/search |
Fetch paginated list of issues |
GET /api/measures/component |
Fetch code coverage percentage for a branch |
| Scenario | Behavior |
|---|---|
config.json missing |
Prints error, exits with code 1 |
| Missing config keys | Prints which key is missing, exits 1 |
SONAR_TOKEN not set |
Prints error, exits with code 1 |
| Invalid SonarQube URL | requests raises ConnectionError |
| Invalid token | SonarQube returns 401 — raises HTTPError |
| Invalid project key | SonarQube returns 404 — raises HTTPError |
| Network timeout | requests raises Timeout |
You can wrap main() in a try/except if you want graceful handling:
try:
violations = main()
except requests.exceptions.HTTPError as e:
print(f"SonarQube error: {e}")
except requests.exceptions.ConnectionError:
print("Could not connect to SonarQube. Check the URL in config.json.")
except json.JSONDecodeError:
print("config.json is not valid JSON.")The included .github/workflows/sonarcloud.yml workflow automatically analyzes your project with SonarCloud on every push and pull request. It will:
- Checkout the repository with full history (
fetch-depth: 0) - Set up Python 3.14
- Install dependencies (
requests,pytest) - Run the full test suite before analysis
- Trigger a SonarCloud scan using
SonarSource/sonarcloud-github-action@v3
This ensures code quality is assessed on every merge, preventing regressions from being merged into your main branch.