CLI

CI setup

Symbol upload belongs in CI, not on someone's laptop. It has to run on every build, right after the build, with the release the deploy will actually report.

The three rules

Store the credentials as secrets

MONITORING_URL, MONITORING_TOKEN, and MONITORING_ENVIRONMENT. The token is an ingest credential, so treat it like any other secret.
Upload immediately after the build

Source maps only exist between the build and the deploy. Upload before the artifacts are discarded.
Let the release default

Inside a git checkout the CLI resolves the release from git rev-parse HEAD. Pass --release explicitly only if your SDK reports something else.

GitHub Actions

- name: Build
  run: npm run build

- name: Upload source maps
  run: npx @octri/monitoring-cli sourcemaps upload ./dist
  env:
    MONITORING_URL: ${{ secrets.MONITORING_URL }}
    MONITORING_TOKEN: ${{ secrets.MONITORING_TOKEN }}
    MONITORING_ENVIRONMENT: ${{ secrets.MONITORING_ENVIRONMENT }}

actions/checkout defaults to a shallow clone

fetch-depth: 1 still gives you HEAD, so git rev-parse HEAD works. But if your workflow builds from an artifact or a container without the .git directory, the release can't resolve and the CLI exits 1. Pass --release ${{ github.sha }} in that case.

GitLab CI

upload-sourcemaps:
  stage: deploy
  script:
    - npm run build
    - npx @octri/monitoring-cli sourcemaps upload ./dist
  variables:
    MONITORING_RELEASE: $CI_COMMIT_SHA

MONITORING_URL, MONITORING_TOKEN, and MONITORING_ENVIRONMENT go in the project's CI/CD variables, masked.

Shell

export MONITORING_URL="https://monitoring.example.com"
export MONITORING_TOKEN="$INGEST_TOKEN"
export MONITORING_ENVIRONMENT="$PROJECT_ENV_ID"

npm run build
octri-monitoring sourcemaps upload ./dist

The release has to match the deploy

Uploading a different SHA than you deploy is the same as not uploading

If CI builds abc123, uploads symbols for abc123, and then deploys an artifact built from def456, monitoring has symbols under a release nothing reports. Every trace stays minified and nothing warns you.

One build, one SHA, one upload, one deploy. If your pipeline separates build and deploy, thread the same SHA through both.

Failing the build

The CLI exits 1 when a path matches no files, which is what you want: a silent no-op means you find out weeks later, mid-incident, that you have no symbols.

Don't make the upload step non-blocking

|| true on this step turns a loud failure into a silent one. If the upload can't find your maps, the build is already wrong.

Delete maps before deploying

npm run build
npx @octri/monitoring-cli sourcemaps upload ./dist
find ./dist -name '*.map' -delete
npm run deploy

See Source maps.

Releases

What the release id feeds.

CLI reference

Every flag.