@omniboard/analyzer

Getting started with Omniboard in less than 5 minutes (video)

Create account, get API key and define checks

1. Create free account for Omniboard.dev
2. Generate API key in the Omniboard.dev (docs)
3. Set API key as an OMNIBOARD_API_KEY environment variable (or pass it in using --api-key flag when running omniboard command, never commit your API key to the version control system)
4. (optional) test your API key using npx omniboard test-connection --api-key <your-api-key> (same as omniboard tc --ak <your-api-key>)
5. Define checks in the Omniboard.dev app

Run in projects

Make sure you have already set OMNIBOARD_API_KEY environment variable in the given environment (CI) or pass it in using --api-key flag when running omniboard command locally

1. install it using npm i -D @omniboard/analyzer in the project we want to analyze (dev dependency)
2. run it using npx omniboard (or run omniboard as a npm script, eg "postbuild": "omniboard"")

or

• npx @omniboard/analyzer (in case it was not pre-installed)

or

• npm i -g @omniboard/analyzer - install it globally to be able to run omniboard in any path without waiting for npx install

Commands

• omniboard analyze - (same as omniboard) analyze project and upload results to Omniboard.dev, or store results locally with --json
• omniboard batch - Clone (or update) and analyze multiple project repositories and upload results to Omniboard.dev, or store results locally with --json
• omniboard test-connection - test connection to the Omniboard.dev app
• omniboard test-check - test check definition provided as a CLI argument (can be copied from the Omniboard.dev app)

How it works - analyze

1. retrieve current checks defined in the Omniboard.dev app
2. run retrieved checks for the current project (skip checks that are disabled or if project name does not match provided pattern)
3. store check results locally when --json flag was present
4. upload checks results to the Omniboard.dev app when --json is not present and OMNIBOARD_API_KEY env variable or --api-key flag is present
5. Explore results in the Omniboard.dev app using projects, results or dashboards overview

How it works - batch

Setup

1. on the first run, create empty workspace and job file (if not present)
2. (manual step) add repository urls to the job file (in queue array)

Execution

1. batch asks the Analyzer planning API whether each repository should be analyzed or skipped as unchanged

2. batch clones (or updates) repositories whose decision is analyze

3. batch runs omniboard analyze, uploads the project, and records the successful analysis for future planning

4. batch moves each repository from queue into exactly one outcome collection: analyzed, skipped, or failed; use --preserve-queue to retain queue entries for repeated runs

5. skipped entries include one reason: unchanged, excluded, or unresolved

6. batch repeats these steps until every queued repository is processed

7. batch prints the final outcome counts and non-zero skip-reason counts, for example:

   Batch results, queue: 0, analyzed: 45, skipped: 5 (unchanged: 4, excluded: 1), failed: 0

The batch job file uses this shape:

{
  "queue": [],
  "analyzed": ["https://example.com/analyzed.git"],
  "skipped": [
    {
      "source": "https://example.com/skipped.git",
      "reason": "unchanged"
    }
  ],
  "failed": []
}

This is a breaking format. Recreate older job files that contain done or completed.

Options

Run omniboard --help or omniboard <command> --help for the complete yargs-generated help.

For boolean options, passing the flag means true (for example, --telemetry). Pass false explicitly to disable it (for example, --telemetry false). Negated forms such as --no-telemetry are not supported.

Global

--verbose                    Display debug level logs                       [boolean] [default: false]
--silent                     Silence renderer output                        [boolean] [default: false]
--show-check-results         Show individual check results in log output    [boolean] [default: false]
--api-key, --ak              API key generated in Omniboard.dev             [string]
--api-url, --api             URL of an on-prem Omniboard instance           [string]
--expected-group             Fail if the API key targets another group      [string]
--errors-as-warnings         Exit successfully when analysis errors occur   [boolean] [default: false]
--help, -h                   Show help                                      [boolean]
--version, -v                Show version number                            [boolean]

In CI, pass --expected-group <group> to analyze, batch, or test-connection. The Analyzer then verifies the API key destination and stops before analysis or upload when the authenticated group does not match. Without this flag, analyze and batch do not make the additional connection check.

analyze

--json                       Store results locally and skip upload          [boolean] [default: false]
--json-path                  Local results path                 [string] [default: "./dist/omniboard.json"]
--check-pattern, --cp        Run only checks matching the pattern           [string]
--telemetry                  Report analyzer performance telemetry          [boolean] [default: false]
--sanitize-repo-url, --sru   Sanitize authentication tokens in repository URLs
                                                                            [boolean] [default: true]

batch

--skip-unchanged             Skip repositories with matching successful analysis state
                                                                            [boolean] [default: true]
--job-path                   Batch job file                     [string] [default: "./omniboard-job.json"]
--preserve-queue             Preserve the queue for repeated runs           [boolean] [default: false]
--workspace-path             Batch workspace                    [string] [default: "./omniboard-workspace"]
--json                       Store results locally and skip upload          [boolean] [default: false]
--check-pattern, --cp        Run only checks matching the pattern           [string]
--sanitize-repo-url, --sru   Sanitize authentication tokens in repository URLs
                                                                            [boolean] [default: true]
--telemetry                  Report analyzer performance telemetry          [boolean] [default: true]

test-check

--check-definition, --cd     Check definition as JSON                       [string]
--json                       Store results locally                          [boolean] [default: false]
--json-path                  Local results path                 [string] [default: "./dist/omniboard.json"]

FAQ

Is it possible to run @omniboard/analyzer behind organization proxy?

Yes

The @omniboard/analyzer uses global-agent library which will uses HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables and use them to make requests to https://api.omniboard.dev

Is this uploading my source code to the cloud?

No

The @omniboard/analyzer runs checks against your source code (or even generated artifacts) and uploads results of these checks to the cloud service for further processing. The uploaded content is then just metadata describing the projects and results but NOT the projects themselves.

In theory, a check which matches everything could be constructed but such result will be rejected as the payload would be too large. The limits of how much data can be stored per check and per all checks for a project can be customized in organization settings in the Omniboard.dev app.