# 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.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/guides/source-maps-in-ci/

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](https://docs.sypnia.com/sdks/nextjs).

**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

1. **One name for the release.** The string you pass to `init` as `release` and the string you upload for must be identical. Use the short git commit for both.
2. **Upload after bundling, before deploying.** The maps must be in Sypnia before the first visitor loads the new code.
3. **Never publish the maps.** They contain your source code. The upload command deletes them from the build output.

## Set it up

### 1. Make the build write source maps, and know its release

**Vite**

`vite.config.ts`

```ts
import { defineConfig } from 'vite';

export default defineConfig({
  build: { sourcemap: 'hidden' },
  define: { __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') },
});
```

`src/main.ts`

```ts
import { init } from '@sypnia/browser';

declare const __RELEASE__: string;

init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  release: __RELEASE__ || undefined,
});
```

**webpack**

`webpack.config.js`

```js
const webpack = require('webpack');

module.exports = {
  devtool: 'hidden-source-map',
  plugins: [new webpack.DefinePlugin({ __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') })],
};
```

**esbuild**

```bash
esbuild src/main.ts --bundle --minify --sourcemap=external --outdir=dist \
  --define:__RELEASE__="\"$RELEASE\""
```

`hidden` (or `external`) writes the `.map` files without a comment in the JavaScript that points at them.

**You should see:**After `RELEASE=4f2a91c npm run build`, `dist` holds `.js` files and a `.map` next to each.

### 2. Create the token and store it as a secret

```bash
sypnia token create --project shop --name "CI source maps" --scopes admin
```

On Sypnia Cloud you can also create it in the app. Copy the `sps_…` value into your CI's secrets as `SYPNIA_API_TOKEN`. In GitHub: the repository's **Settings**, then **Secrets and variables**, then **Actions**.

**You should see:**A secret named `SYPNIA_API_TOKEN` in your CI. The token is not in the repository.

### 3. Add the upload to the workflow

**Sypnia Cloud**

`.github/workflows/deploy.yml`

```yaml
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 deploy
```

**Self-hosted**

`.github/workflows/deploy.yml`

```yaml
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 deploy
```

**You should see:**

```text
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](https://docs.sypnia.com/cli). 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](https://docs.sypnia.com/concepts/releases-and-source-maps).

## Check that it worked

```bash
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**You should see:**Each file with `"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](https://docs.sypnia.com/sdks/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](https://docs.sypnia.com/api/releases-and-source-maps) in the API reference.
