| name | codacy-audit |
| description | 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 in the current SOW; write actions (mark FP, mark fixed) are deferred. |
Codacy audit skill
Drives Codacy Cloud for netdata/netdata:
- 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.
- 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:
coverity-audit/, sonarqube-audit/, graphql-audit/, codacy-audit/. Same shape, same conventions, same artifact 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 (current SOW)
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 (deferred to a future 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_ORG | Defaults to netdata. |
CODACY_REPO | Defaults to netdata. |
All values 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/codacy-audit/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.
Operational gotcha: when the Dockerized Codacy CLI fails before a tool can emit
results, the output file may have a .json suffix but contain tool-runner logs
instead of JSON. Always verify with jq empty <dump> before treating a local
dump as finding evidence. 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.
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.
To restrict to a single tool (matches what Codacy reported on a CI run):
$ .agents/skills/codacy-audit/scripts/analyze-local.sh --tool markdownlint
Workflow -- PR triage
$ .agents/skills/codacy-audit/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/sow/specs/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/coverity-audit/ -- Coverity Scan (same triage shape)..agents/skills/sonarqube-audit/ -- SonarCloud (same triage shape)..agents/skills/graphql-audit/ -- GitHub Code Scanning / CodeQL (same triage shape).
Token-safe self-test
Before trusting wrappers in a long-running session, run the self-test:
$ source .agents/skills/codacy-audit/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.
