CLI CI gate (BYOT)

Upload a CI-built dependency tree (lockfile or Maven CycloneDX) with the CodeCleared CLI, scan existing project units in parallel, and wait for verdicts.

Purpose

Use the CodeCleared CLI in CI when the server cannot resolve private dependencies (for example Maven with build credentials). The runner collects the package tree locally and uploads it; CodeCleared still binds the scan to a connected repository, existing project unit, and commitHash.

Who

Engineers wiring CI quality gates. Organization owners provide a service token.

Prerequisites

Connected repository, active dependency project units, API access, and credits. Clone the CLI package (codecleared.io/cli) and npm link — it is not published to npm yet.

Steps

export CODECLEARED_API_TOKEN=...
# optional override; default is https://api.codecleared.io/api
# export CODECLEARED_API_URL=https://api.example/api

codecleared scan \
  --full-name owner/repo \
  --commit "$COMMIT_SHA" \
  --branch main \
  --wait

Without --project-unit-id, every matchable project unit is scanned in parallel (Promise.all).
With --project-unit-id, only that unit is scanned.
--artifact lockfile|sbom overrides auto-detection.
--scan-types sca (comma-separated) limits which activities run. Prefer sca for Maven BYOT / private deps. Allowed: sbom, sca, license, dependency-advisor, secrets, sast, all.
With --wait, summary only includes keys for requested types (sca → vulnerabilities only; no empty secrets / licenses).
Wait verdict uses org apiGateSeverityThreshold (default critical; Settings → Scan defaults). FAIL if ≥1 vuln / secret at or above that threshold, or a non-compliant license. Not Quality Gates; separate from PR prCheckSeverityThreshold. Reasons keep critical_* when threshold is critical, else vulnerabilities_above_threshold / secrets_above_threshold. summary.severityThreshold echoes the threshold used. See Scans API.
CLI skipped entries use kind: project-unit (PU out of scope), scan-type (activity not requested on a triggered PU), artifact (collection failure).
Bad / inaccessible --commit → wait ends with errorCode: branch_or_commit_not_found (orchestrator marked failed in Temporal — not a client-side timeout).
A job that exceeds Temporal limits ends with errorCode: workflow_timeout (server-side); that is distinct from a client --wait / API wait deadline, which expires while the scan may still be running.
Exit codes with --wait: 0 PASS, 1 FAIL, 2 ERROR (API / timeout / system).

Artifact contracts

Ecosystem	Artifact	Notes
npm / yarn / pnpm / pip / gem / Cargo / composer / gomod	Lockfile upload	Raw lockfile content + path (`go.sum` preferred, else `go.mod`)
Gradle	`*.gradle.lockfile`	Enable dependency locking in CI
Maven	CycloneDX SBOM	Generate with the CycloneDX Maven plugin, then upload as `sbom`
secrets / sast	None	Trigger only (`sourceTrigger=api`); not BYOT

Do not install or invoke server scanners on the runner. Analysis stays on CodeCleared.

CLI vs curl Actions

Use	When
CLI	Private registries / Maven build creds / BYOT tree
curl `POST /v1/scans` without artifact	Server can clone and read the lockfile (standard GitHub Actions guide)

Both paths share the same credit gate (402). Uploading an artifact sets sourceTrigger=cli and skips commit-hash dedup (always a new job).

Snapshot priority & BYOT badge

Governance “latest scan” preference: cli > api | push | manual-ui > scheduled (pr-event excluded). In the UI, CLI results show a BYOT badge: the dependency tree came from CI and may differ from a pure server git clone.

Limits

Body size ≤ 10 MB per BYOT upload. Secrets/SAST can be triggered from the CLI without an artifact (classic API path). Maven BYOT needs mvn on PATH or a pre-generated target/bom.json; a Maven collect failure does not cancel other project-unit scans.