Source maps in CI
Upload source maps and register the release from your build, with a complete GitHub Actions example, so stacks show your own files and problems say which change started them.
This guide is for whoever owns the build. It works the same for Sypnia Cloud and for a self-hosted engine; only one variable differs. For a Next.js app you do not need it: @sypnia/next uploads source maps during next build, see Next.js.
At the end you will have: every deploy registered as a release with its commit, its source maps stored privately in Sypnia, and no .map file published with your site.
You need: a project, a build that can write source maps, and an API token with the admin scope.
The three rules
- One name for the release. The string you pass to
initasreleaseand the string you upload for must be identical. Use the short git commit for both. - Upload after bundling, before deploying. The maps must be in Sypnia before the first visitor loads the new code.
- Never publish the maps. They contain your source code. The upload command deletes them from the build output.
Set it up
Make the build write source maps, and know its release
Vite
vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ build: { sourcemap: 'hidden' }, define: { __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') }, });src/main.ts import { init } from '@sypnia/browser'; declare const __RELEASE__: string; init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', release: __RELEASE__ || undefined, });webpack
webpack.config.js const webpack = require('webpack'); module.exports = { devtool: 'hidden-source-map', plugins: [new webpack.DefinePlugin({ __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') })], };esbuild
Terminal esbuild src/main.ts --bundle --minify --sourcemap=external --outdir=dist \ --define:__RELEASE__="\"$RELEASE\""hidden(orexternal) writes the.mapfiles without a comment in the JavaScript that points at them.You should seeAfterRELEASE=4f2a91c npm run build,distholds.jsfiles and a.mapnext to each.Create the token and store it as a secret
Terminal sypnia token create --project shop --name "CI source maps" --scopes adminOn Sypnia Cloud you can also create it in the app. Copy the
sps_…value into your CI’s secrets asSYPNIA_API_TOKEN. In GitHub: the repository’s Settings, then Secrets and variables, then Actions.You should seeA secret namedSYPNIA_API_TOKENin your CI. The token is not in the repository.Add the upload to the workflow
Sypnia Cloud
.github/workflows/deploy.yml name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # the upload reads the commits since the previous release - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci - name: Name the release run: echo "RELEASE=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV" - run: npm run build - name: Upload source maps to Sypnia run: npx sypnia sourcemaps upload dist --release "$RELEASE" --delete-after env: SYPNIA_API_TOKEN: ${{ secrets.SYPNIA_API_TOKEN }} - name: Deploy run: npm run deploySelf-hosted
.github/workflows/deploy.yml name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # the upload reads the commits since the previous release - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci - name: Name the release run: echo "RELEASE=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV" - run: npm run build - name: Upload source maps to Sypnia run: npx sypnia sourcemaps upload dist --release "$RELEASE" --delete-after env: SYPNIA_API_TOKEN: ${{ secrets.SYPNIA_API_TOKEN }} SYPNIA_BASE_URL: https://sypnia.example.com - name: Deploy run: npm run deployYou should seeText release 4f2a91c (production), previous 9c1e7b2: 1 commit, 2 files changed found 42 JavaScript files with a source map uploaded 41 maps (6.2 MB), skipped 1 already there deleted 42 .map files from dist done in 3.4 s
What the command needs to know
| Flag | When you need it |
|---|---|
<directory> | The build output: dist, build, .output/public. |
--release | Always. The same string as release in init. |
--url-prefix | When the directory is not served from the root of your site. With dist/assets/a.js served as /static/assets/a.js, pass --url-prefix /static. |
--environment | When the deploy is not production: --environment staging. |
--delete-after | Almost always: it removes the .map files so they are not published. |
--allow-failure | When a deploy must never wait for Sypnia. The command then prints the error and exits 0; that release’s stacks stay minified. |
--patches | To also send each changed file’s diff, which makes the analysis sharper. The diffs are your source code and go to the AI provider with the analysis. |
--dry-run | To see what would be sent. |
Every flag is in the CLI reference. Outside GitHub Actions the same three lines work anywhere: name the release, build, upload.
What registering the release adds
The same command registers the release with what git knows: the commit, the commits since the previous release and the files they changed. That is what lets a problem say «since yesterday’s change» and name the change. On Sypnia Cloud with the GitHub App installed, the agent can also read the difference between the two commits itself. See Releases and source maps.
Check that it worked
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN""uploaded": true, and url_path equal to the path your site serves it from, such as /assets/checkout-3f9c.js.Then look at the next occurrence of any problem in that release: its stack reads src/checkout/checkout.tsx:142 instead of checkout-3f9c.js:1:48211. If it does not, the table in Troubleshooting lists the causes, most often a release name that differs by a few characters.
Without the CLI
The upload is two API calls: ask for upload links, then PUT each map. Use them from a build system that cannot run the command. See Releases and source maps in the API reference.