# Triage Codacy

> Codacy Cloud workflow for this repository -- run Codacy's analyzers locally before `git push` (mirrors what Codacy CI runs), and fetch/cluster Codacy issues for any PR via the v3 API. Use when the user mentions Codacy, "codacy analysis", `codacy-analysis-cli`, "codacy issues on PR", "fix codacy CI", "codacy markdownlint findings", or any Codacy gate failing on a netdata-org PR. Ships scripts analyze-local.sh (docker/binary runner for codacy-analysis-cli) and pr-issues.sh (paginated v3 issue fetch + group-by tool/pattern/severity/file). Token-safe -- CODACY_TOKEN never reaches assistant-visible stdout. Read-only by design; write actions (mark FP, mark fixed) require a GitHub issue or branch-local SOW.

- Skill: `netdata/triage-codacy` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add netdata/triage-codacy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/netdata/triage-codacy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: netdata (https://skillmd.com/u/netdata)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/netdata/triage-codacy

---


# Codacy audit skill

Drives Codacy Cloud for `netdata/netdata`:

1. **Pre-push prevention** -- run the same analyzers Codacy CI runs, locally, before `git push`. Collapses the "push -> wait minutes -> see findings -> fix -> push again" loop into one push.
2. **Read-only PR triage** -- list Codacy issues for any PR, cluster by tool / pattern / severity / file, drop the JSON dump under `<repo>/.local/audits/codacy/`.

This skill is the fourth in the static-analysis triage family in this repo:
`triage-coverity/`, `triage-sonarqube/`, `triage-codeql/`, `triage-codacy/` share one shape and one set of conventions;
each keeps its own `.local/audits/<dir>/` (root `AGENTS.md`, Local-Only Working Directory).

## MANDATORY -- keep this skill alive

If you (the assistant) discover a new pattern, gotcha, working flow, correction, or any operational knowledge while running this skill -- update this `SKILL.md` AND commit it BEFORE proceeding. Knowledge that isn't committed is lost.

Examples worth capturing:
- New v3 API endpoint or response-shape detail learned the hard way
- Codacy-side rate-limit signals
- A pattern Codacy mismodels for this codebase (so the next assistant can add a path exclusion or mark it FP)
- A new tool the local CLI gained / lost
- Auth-failure surface (e.g. token type mismatch, expired token signs)

## MANDATORY -- live how-tos catalog

Each concrete question that requires non-trivial analysis (multiple wrapper calls, jq pipelines, cross-referencing other skills) MUST become a how-to under `how-tos/<slug>.md` AND get an entry in `how-tos/INDEX.md` BEFORE the task is reported complete. Skipping this means the next assistant repeats the analysis from scratch.

## Scope

In scope:

- Local pre-push analysis via `codacy-analysis-cli` (auto-detects local binary, falls back to docker).
- Read-only PR-issue queries against the v3 API.
- Token-safe wrappers (sentinel-driven no-leak self-test).

Out of scope until a real use case creates a GitHub issue or branch-local SOW:

- Write actions (mark issue as false-positive, mark as fixed, modify ignore-patterns).
- Master-backlog triage on the 31,425+ open issues.
- Cross-repo aggregation across the netdata org.

## Required env keys

| Key | Required for |
|---|---|
| `CODACY_TOKEN` | Account API token, header `api-token: <value>`. Required by `pr-issues.sh` and any wrapper that calls `_codacyaudit_run`. NOT required by `analyze-local.sh` (the CLI runs anonymously). |
| `CODACY_HOST` | Defaults to `https://api.codacy.com`. Override only if Codacy moves the API host. |
| `CODACY_PROVIDER` | Defaults to `gh` (GitHub). |
| `CODACY_CLI_VERSION` | Optional, not a secret, and read from the process environment only (`analyze-local.sh` does not source `.env`): `CODACY_CLI_VERSION=1.2.3 analyze-local.sh` pins the docker image tag; defaults to `latest`. |
| `CODACY_ORG` | Defaults to `netdata`. |
| `CODACY_REPO` | Defaults to `netdata`. |

All values except `CODACY_CLI_VERSION` live in `<repo>/.env` (gitignored). See `<repo>/.agents/ENV.md` for setup (where
each value comes from, sample formats, common mistakes).

## Scripts (in scripts/)

| Script | Purpose |
|---|---|
| `_lib.sh` | Helpers (`codacyaudit_*` prefix). Token-safe; ships `codacyaudit_selftest_no_token_leak`. |
| `analyze-local.sh` | Run `codacy-analysis-cli` locally; auto-pick local-binary or docker; write JSON dump under `.local/audits/codacy/`. |
| `pr-issues.sh` | Fetch all Codacy issues for a PR via the v3 API; cluster summary on stdout; full JSON dump on disk. |

## Workflow -- pre-push prevention

```
$ .agents/skills/triage-codacy/scripts/analyze-local.sh
[analyze-local] runner=docker format=json dir=<repo>
[analyze-local] wrote 0 finding(s) to <repo>/.local/audits/codacy/local-<ts>.json
```

Run this before `git push`. If it returns 0 findings, the Codacy gate on the PR will be green (modulo Codacy server-side patterns the local CLI doesn't bundle). If it returns findings, fix them locally first.

Failed analyses are not clean trees: when the dump is not JSON, is JSON of the
wrong shape (not a findings array, an `{issues: [...]}` object, or a SARIF `runs`
document), or the CLI exits non-zero with zero findings, the script exits 4 and
keeps the CLI's stderr in `<dump>.log`. Treat exit 4 as "no
evidence", not as green. If GitHub check-run annotations are empty too, use
`pr-issues.sh` with `CODACY_TOKEN`; without that token, record the evidence gap
and re-check after the next push.

One common local cause is gitignored generated output with restrictive file
permissions. For example, if local scratch output under `.local/` contains files
not readable by the Docker container, Codacy logs `Could not read file` messages
and the saved `.json` dump is plain text. Fix or move the local generated output
before trusting local analyzer output.

Operational gotcha: the public Codacy v3 analysis endpoint can expose PR issue
details even when GitHub check-run annotations are empty and no `CODACY_TOKEN`
is available:

```
curl -fsS \
  "https://api.codacy.com/api/v3/analysis/organizations/gh/netdata/repositories/netdata/pull-requests/<PR>/issues?limit=100"
```

Filter for `.data[] | select(.deltaType == "Added")` to identify the issues
that still block the PR. Treat `commitInfo` fields as sensitive operational
metadata; do not copy names or email addresses into committed artifacts.

Operational gotcha: Codacy's PR issue API can lag behind the GitHub check-run
after a new push. If `pr-issues.sh` still reports findings but the Codacy
check-run for the current head SHA is green, inspect `.commitIssue.commitInfo.sha`
in the dump. Findings anchored to an older commit are stale cache and should not
be treated as current-head blockers.

To restrict to a single tool (matches what Codacy reported on a CI run):

```sh
.agents/skills/triage-codacy/scripts/analyze-local.sh --tool markdownlint
```

## Workflow -- PR triage

```console
$ .agents/skills/triage-codacy/scripts/pr-issues.sh 22423
[pr-issues] fetching issues for PR #22423 ...
[pr-issues] wrote 0 issue(s) to <repo>/.local/audits/codacy/pr-22423-<ts>.json

No issues on PR #22423.
```

For a PR with findings, the script emits a clustered TSV summary. Default grouping is `--by pattern`; switch to `--by tool`, `--by severity`, `--by file`, or `--by category` for other angles. The JSON dump under `.local/audits/codacy/` carries the full issue payload for follow-up jq queries.

Operational note: large Codacy PR issue arrays must be passed to `jq` via a
temporary file and `--slurpfile`, not `--argjson`, because shell argument-size
limits can fail before `jq` starts.

## Path discipline

This skill follows `<repo>/.agents/sensitive-data-discipline.md`:

- Repo files: repo-relative (`<repo>/src/...`).
- Codacy account / org / repo identifiers: env-keyed.
- `CODACY_TOKEN`: NEVER literal in any committed file; ALWAYS via `${CODACY_TOKEN}` and the `_lib.sh` wrappers.
- Audit dumps: gitignored under `<repo>/.local/audits/codacy/`.

## Related skills

- `.agents/skills/triage-coverity/` -- Coverity Scan (same triage shape).
- `.agents/skills/triage-sonarqube/` -- SonarCloud (same triage shape).
- `.agents/skills/triage-codeql/` -- GitHub Code Scanning / CodeQL (same triage shape).

## Token-safe self-test

Before trusting wrappers in a long-running session, run the self-test:

```console
$ source .agents/skills/triage-codacy/scripts/_lib.sh
$ codacyaudit_load_env
$ codacyaudit_selftest_no_token_leak
PASS: codacyaudit_selftest_no_token_leak
```

The self-test sets `CODACY_TOKEN` to a sentinel UUID, drives every public wrapper, captures stdout, and asserts the sentinel never appears. Run after editing `_lib.sh` or any wrapper.