ROYALCORE-JS ← Back

CI integration

Run the RoyalCore-JS CLI on your machine or CI runner. The scan reads your repository on that host; source code is not uploaded to us as a project archive. Metering (monthly line quota) is updated via a small HTTPS call after each scan when you configure the variables below.

1. After you subscribe

  1. Sign in on royalcorejs.com and open Pricing / Paketler.
  2. Complete checkout for your plan. When your subscription is active, open the same area where your subscription is shown.
  3. Copy your project key (CLI project key) — this ties scans to your line quota.
  4. If your onboarding email or dashboard lists a usage token, copy it as well; it must be sent with each usage request (see below).
  5. Add the CLI to the repository you want to scan (see section 3), then wire CI using the examples in sections 6–8.

2. Environment variables (metering & behaviour)

Set these in your shell locally or as encrypted secrets in GitHub/GitLab. The CLI reads them at scan time.

Variable Required? Purpose
ROYALCORE_PROJECT_KEY For paid metering Identifies your project; scanned line count is posted to the usage API so your quota stays accurate. Legacy alias: SENTINEL_PROJECT_KEY.
ROYALCORE_USAGE_API_BASE For paid metering API origin, no trailing path — e.g. https://royalcorejs.com. The CLI calls /api/usage on that host. Aliases: ROYALCORE_API_BASE, legacy SENTINEL_*.
ROYALCORE_USAGE_TOKEN If your account uses it When configured on the server, the CLI must send the same value as header X-Usage-Token. Use the token from your dashboard or support. Legacy: SENTINEL_USAGE_TOKEN.
ROYALCORE_FAIL_ON_CRITICAL Optional Default in CI is effectively strict: KRİTİK findings → process exits with code 1. Set to 0 only if you want the scan to warn without failing (e.g. some local git hooks). Legacy: SENTINEL_FAIL_ON_CRITICAL.
ROYALCORE_LANG Optional tr or en for CLI messages and HTML report language. Legacy: SENTINEL_LANG.
ROYALCORE_REPORTS_ROOT Optional Directory for rapor.json, sarif.json, scan-metrics.json, and generated HTML (default: ~/RoyalCoreJSReports). In CI, set this under the workspace (e.g. ${{ github.workspace }}/.royalcore-reports) so artifacts are easy to upload. Legacy: SENTINEL_REPORTS_ROOT.
ROYALCORE_CHANGED_ONLY Optional Set to 1 to scan only paths listed in ROYALCORE_CHANGED_FILES_FILE (one repo-relative path per line). If the list is empty or the file is missing/unreadable, the CLI falls back to a full source walk. Legacy: SENTINEL_CHANGED_ONLY.
ROYALCORE_CHANGED_FILES_FILE With changed-only Absolute path to a UTF-8 text file of changed paths (used when ROYALCORE_CHANGED_ONLY=1). Legacy: SENTINEL_CHANGED_FILES_FILE.
ROYALCORE_MAX_PARSE_FAIL_RATE Optional Maximum allowed parse-failure rate (percent, 0–100). Default 100 effectively disables exit code 2 for parse policy. Lower values can fail the job when too many files fail to parse. Legacy: SENTINEL_MAX_PARSE_FAIL_RATE.

What gets scanned

  • Root: the directory passed to scan (--dir; default is the current working directory). Subdirectories are walked recursively.
  • Skipped directory names: node_modules, .git, dist, coverage.
  • Source extensions: .js, .jsx, .ts, .tsx, .vue.
  • Dependencies: lockfile / npm audit and related checks still run for the whole project at the scan root; they are not narrowed to the changed-file list.

3. Install the CLI and run your first scan locally

From your project root (where package.json lives):

export ROYALCORE_PROJECT_KEY="your_project_key_here"
export ROYALCORE_USAGE_API_BASE="https://royalcorejs.com"
# If your plan requires it:
# export ROYALCORE_USAGE_TOKEN="your_usage_token_here"
# CI-friendly report location (optional locally):
# export ROYALCORE_REPORTS_ROOT="$PWD/.royalcore-reports"
# (Eski SENTINEL_* değişkenleri hâlâ okunur.)

# Install deps if you have a Node project; then scan repo root
npm ci
npx --yes @royalcorejs/core-js@latest scan --dir .

Alternatives: add a published package as a devDependency (e.g. npm install royalcore-js --save-dev) and run npx royalcore-js scan --dir . if that matches your npm package name. If you develop from a clone of this engine, use node bin/index.js scan --dir ..

4. What each command does

  • scan (via npx @royalcorejs/core-js@latest or your installed CLI) — Walks --dir (default cwd), writes rapor.json, sarif.json, and scan-metrics.json under ROYALCORE_REPORTS_ROOT (default ~/RoyalCoreJSReports); posts line usage when metering env vars are set.
  • scan --html — Same as above plus one HTML report step; quota is charged once for the scan, not again for HTML.
  • report — Regenerates HTML from existing rapor.json in the reports root only; does not consume additional line quota.
  • setup-hooks — Optional local git hooks (pre-commit / pre-push). Can prompt for the project key; supports --key, --mode full|changed, --soft-hooks / --block-on-critical.
    If you install with --mode changed, the pre-push hook performs incremental scanning on scannable changed files. If the diff has no scannable extensions, the hook skips scan for that push (no full fallback, no usage write).
    To run a full scan on demand, use scan --dir . (or install hooks again with --mode full --initial-scan).

4.1 Full vs Changed mode (TR/EN)

EN: If hooks are installed with --mode full, every push runs a full-repo scan. If installed with --mode changed, only changed scannable files are targeted (js/jsx/ts/tsx/vue). If no scannable diff exists, scan is skipped for that push (no full fallback, no usage write).

TR: Hook'lar --mode full ile kurulduysa her push'ta tüm repo taranır. --mode changed ile kurulduysa sadece değişen taranabilir dosyalar taranır (js/jsx/ts/tsx/vue). Diff içinde uygun uzantı yoksa o push için tarama atlanır (full fallback yok, kota yazılmaz).

Switch full → changed

node bin/index.js setup-hooks --mode changed
  • Enter your real project key (not a shell command).
  • Check setup output: Kurulum tamamlandı. Mod: changed.
  • Push once and verify changed-only logs.

Switch changed → full

node bin/index.js setup-hooks --mode full
  • Use this before major release/audit runs.
  • On install output, verify Mod: full.
  • Push scans entire repository.

Verification checklist / Doğrulama listesi

  • Mode: setup output shows expected mode (full or changed).
  • Usage: push logs include Usage API çağrılıyor and Kullanım güncellendi.
  • Database: in projects, verify the exact project_key row updates line_count_this_period.

TR — Net fark (push sırasında)

Mod Push'ta ne olur? Kota etkisi
--mode full Her push'ta proje geneli tarama yapılır (repo içindeki taranabilir tüm dosyalar). Taranan satır kadar kota yazılır.
--mode changed Sadece değişen .js/.jsx/.ts/.tsx/.vue dosyaları taranır. Uygun uzantı yoksa push'ta tarama atlanır. Sadece taranan değişiklik satırları kadar kota yazılır; tarama atlanırsa kota yazılmaz.

EN — Clear difference (during push)

Mode What happens on push? Quota impact
--mode full Runs a full project scan on every push (all scannable files in the repository). Quota is charged based on scanned lines.
--mode changed Scans only changed .js/.jsx/.ts/.tsx/.vue files. If no scannable extension changed, scan is skipped for that push. Quota is charged only for scanned changed lines; if scan is skipped, no quota is charged.

5. Exit codes (for CI gates)

  • 0 — Scan finished; no blocking condition (no critical finding under strict policy, and parse-fail rate within threshold).
  • 1 — At least one KRİTİK finding and strict mode is on (default for plain scan in CI). Use this to block merges.
  • 2 — Parse-failure rate exceeded ROYALCORE_MAX_PARSE_FAIL_RATE (legacy SENTINEL_*; default 100% = disabled); only when strict fail-on-critical is enabled.

6. GitHub Actions

Create .github/workflows/royalcore-js.yml. Repository secrets: ROYALCORE_PROJECT_KEY; ROYALCORE_API_BASE (mapped below to ROYALCORE_USAGE_API_BASE, e.g. https://royalcorejs.com); optional ROYALCORE_USAGE_TOKEN. Legacy SENTINEL_* names still work in the CLI.

name: RoyalCore-JS security scan

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  scan:
    runs-on: ubuntu-latest
    env:
      ROYALCORE_PROJECT_KEY: ${{ secrets.ROYALCORE_PROJECT_KEY }}
      ROYALCORE_USAGE_API_BASE: ${{ secrets.ROYALCORE_API_BASE }}
      ROYALCORE_USAGE_TOKEN: ${{ secrets.ROYALCORE_USAGE_TOKEN }}
      ROYALCORE_REPORTS_ROOT: ${{ github.workspace }}/.royalcore-reports
      ROYALCORE_LANG: en
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # Remove this step if the repo has no package.json / is not a Node project.
      - name: Install dependencies
        run: npm ci
        continue-on-error: true

      - name: Run RoyalCore-JS scan
        run: npx --yes @royalcorejs/core-js@latest scan --dir .

If you do not use a usage token, remove the ROYALCORE_USAGE_TOKEN line and the secret. If usage returns 401, the token is required or incorrect. Optionally add a step to upload .royalcore-reports as an artifact (JSON, SARIF, HTML after scan --html).

7. GitLab CI

Define masked variables in GitLab project settings for ROYALCORE_PROJECT_KEY and optionally ROYALCORE_USAGE_TOKEN.

royalcore-js-scan:
  image: node:20
  stage: test
  variables:
    ROYALCORE_USAGE_API_BASE: "https://royalcorejs.com"
    ROYALCORE_REPORTS_ROOT: "$CI_PROJECT_DIR/.royalcore-reports"
    ROYALCORE_LANG: "en"
  script:
    - npm ci || true
    - npx --yes @royalcorejs/core-js@latest scan --dir .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == "main"

Add ROYALCORE_PROJECT_KEY and ROYALCORE_USAGE_TOKEN via CI/CD variables (masked/protected), not committed to YAML.

8. Other CI (Jenkins, Circle, Buildkite, …)

  1. Check out the repository.
  2. Install Node.js 18+ or 20+ and project dependencies (npm ci).
  3. Run the CLI with npx --yes @royalcorejs/core-js@latest scan --dir . (or install your published package name if different).
  4. Export or inject ROYALCORE_PROJECT_KEY, ROYALCORE_USAGE_API_BASE, optional ROYALCORE_REPORTS_ROOT, and token if needed.
  5. Run the scan from the repo root (or pass --dir explicitly).
  6. Mark the job failed if exit code is 1 (or 2 when parse policy is strict).
Reports: Machine-readable outputs (rapor.json, sarif.json, scan-metrics.json) and HTML from scan --html or report go under ROYALCORE_REPORTS_ROOT. Upload that directory as a CI artifact if you want it in the UI. Line quota applies to scanned source lines (skipped dirs such as node_modules are not walked), not to regenerating HTML from existing JSON.