--- name: codacy-repository-bootstrap description: Prepare a repository for Codacy Cloud, Codacy Cloud CLI, client-side analysis, coverage, MCP, Skills, and quality gates with read-only defaults and stack-specific fallbacks. Use when onboarding repositories to Codacy, auditing existing Codacy setup, querying findings, selecting scanners, or designing CI quality and security gates. --- # Codacy Repository Bootstrap Make Codacy available for every repository without making it the only source of truth or forcing unsupported scanners. ## Component model | Component | Purpose | | --- | --- | | Codacy Cloud | Central repository, pull request, issue, coverage, security, and organization view | | Codacy Analysis CLI | Runs supported local or containerized tools and uploads results | | Codacy Cloud CLI | Queries and manages Codacy Cloud data; supports JSON output | | Codacy Skills | Natural-language workflows layered on the Cloud CLI | | Codacy MCP | Agent tool interface for Codacy and local analysis | | Codacy Guardrails | IDE-first analysis and agent feedback using CLI and MCP | | Coverage Reporter | Uploads coverage produced by the repository's own test tools | ## Operating principles - Check current official documentation before installation or configuration. - Default agent and broker access to read-only operations. - Do not automatically ignore findings, lower severity, relax coding standards, remove repositories, or bypass quality gates. - Keep the repository's deterministic local tools and CI authoritative. - Avoid duplicate analysis when Codacy Cloud, a client-side tool, and repository CI run equivalent scanners. - Request machine-readable JSON from the Cloud CLI and pass agents only changed, high-impact findings. - Store full raw results as CI artifacts where appropriate, not in prompt context. - Never commit `CODACY_API_TOKEN`, `CODACY_ACCOUNT_TOKEN`, coverage tokens, or generated credentials. ## Workflow ### 1. Inventory the repository Determine Git provider, owner, repository, default branch, visibility, languages, frameworks, package managers, build systems, generated code, existing lint/typecheck/compile/test/coverage/SAST/SCA/secret/IaC/container/DAST tools, and existing Codacy organization, coding standard, gate, coverage, and status checks. Record unusual stacks such as Unity, IL2CPP, Lua, Android, monorepos, generated bindings, or vendored code. ### 2. Build a Codacy readiness profile Classify Cloud analysis, Cloud CLI, Skills, MCP, Guardrails, client-side tools, coverage, coding standards, quality gates, security findings, and authorized DAST as `AVAILABLE`, `ENABLED`, `PILOT`, `BLOCKED`, or `NOT_APPLICABLE_TO_CAPABILITY`. A capability may be not applicable. Codacy as a whole must still receive an explicit assessment. ### 3. Select analysis paths Use the smallest non-duplicative set. - **Cloud analysis:** centralized repository and pull-request visibility when plan, language, repository size, and data policy permit it. - **Containerized client-side tools:** Codacy Analysis CLI where a supported image exists. On GitHub, evaluate the official Codacy Analysis CLI Action. - **Standalone tools:** run the scanner locally, convert supported output, and upload it. Locally managed standalone tools are not configured in the Codacy UI. Stack-specific checks: - Java or Scala: evaluate SpotBugs and Find Security Bugs. - Unity C#: evaluate Unity Roslyn Analyzers. - JavaScript, TypeScript, Python, Java, Kotlin, C#, Rust, PHP, Shell, Dockerfile, GitHub Actions, and Terraform: evaluate current Semgrep coverage. - Android: retain Gradle lint, unit tests, instrumentation tests, dependency checks, and manifest checks. - .NET and IL2CPP-related repositories: retain compiler analyzers, tests, nullable analysis, dependency audit, and Unity-specific tools. - Unsupported stacks: use best-of-breed local scanners, SARIF or CI artifacts, and GitHub required checks. ### 4. Configure Cloud CLI The official Cloud CLI currently installs as `@codacy/codacy-cloud-cli`. - Interactive: use `codacy login`. - CI: provide `CODACY_API_TOKEN` as a secret. - Use `--output json` for automation. - Limit output to the organization, repository, branch, pull request, severity, category, or changed files needed. - Treat add, remove, reanalysis, coding-standard, follow/unfollow, and ignore operations as writes requiring approval. Reduce context by saving raw JSON as an artifact, normalizing `tool`, `rule_id`, `file`, `line`, `fingerprint`, and `commit`, deduplicating, and sending only new Critical/High findings, changed-file findings, gate failures, and coverage regressions to the agent. ### 5. Configure Codacy Skills and MCP Read [references/official-sources.md](references/official-sources.md). Review the official Skills repository before import. Do not vendor or install an unpinned mutable copy organization-wide without provenance review. Codacy Skills may expose write workflows such as ignoring findings. Use a read-only subset by default. For MCP: - separate repository, issue, security, coverage, and pull-request reads from reanalysis and administrative writes; - use `CODACY_ACCOUNT_TOKEN` only where current official setup requires it; - pin `CODACY_CLI_VERSION` where supported; - keep tokens in client secret storage or environment variables; - compare direct local MCP with the read-only `meyer-mcp` Codacy broker before adding another remote credential path. ### 6. Configure coverage and gates Coverage must be produced by the native test tool and uploaded separately. Do not manufacture coverage to satisfy a gate. A pull-request gate should consider native lint/compile/typecheck, tests, coverage delta, local security and dependency tools, Codacy changed findings, Codacy quality/security gates, and explicit exceptions with owner, reason, and expiry. Codacy must not be the only required check. ## Credential model - `CODACY_API_TOKEN`: Cloud CLI and non-interactive Cloud operations where officially supported. - `CODACY_ACCOUNT_TOKEN`: MCP or Guardrails where officially required. - Repository or coverage tokens: only for the specific supported upload path. Use separate tokens by organization, environment, and purpose. Apply minimal permissions, rotation, expiration, and log redaction. ## Report format Return: 1. repository and Codacy inventory; 2. supported and unsupported capabilities; 3. selected Cloud, local, CLI, MCP, Skills, Guardrails, and coverage paths; 4. duplicate-analysis decisions; 5. required secrets by name and scope; 6. CI and merge-gate design; 7. files changed and checks run; 8. cost, plan, data-policy, and manual activation constraints.