External sourcemap retrieval (template URLs + secrets)

This guide explains how to configure the N|Solid Console to automatically fetch sourcemaps from any external endpoint using URL templates, bearer tokens or S3-type authentication, and metadata key:value pairs (tags).

What the console does

• You save an external storage config (URL template, auth type, credentials, enabled flag).
• When a profile is missing a sourcemap, the console resolves the template using the profile’s metadata (app name and tags) and downloads the zip from the resolved URL.
• Downloads are validated for SSRF safety (HTTPS/S3 only, no localhost/private IPs) and for valid .map files before being stored and linked to the profile.

Prerequisites

• For template variables that use tags, agents must be started with matching --tag flags (e.g., --tag build:1234).
• Ensure the external endpoint serves a zip that contains at least one valid sourcemap (*.map).

URL templates and metadata substitution

Supported placeholders in urlTemplate:

• {app} → the asset’s app name.
• {tag:build} → value after build: from the first matching tag.
• {tag:*} → value after the first tag that contains a : (wildcard key-value pair).

Examples:

• HTTPS with build tag: https://cdn.example.com/maps/{app}/{tag:build}.zip
• S3 object URL: s3://my-bucket/{app}/{tag:*}/dist.zip

If a required placeholder is missing in metadata (no app, or missing tag), the fetch is rejected. If a fetch fails, users can still manually upload sourcemaps.

Per process / per profile resolution

Per process

If a profile is missing a sourcemap, the console will attempt to fetch it from the external endpoint using the URL template and metadata substitution. The sourcemap will be shared across all profiles for that process, autoresolving and avoiding the need to upload them manually for each one.

Per profile

With per profile resolution, there will be no auto resolution of sourcemaps. And the user will have to manually upload the sourcemap for each profile.

Auth options

• Bearer Tokens: Sends Authorization: Bearer <token> when fetching the URL. Use for HTTPS endpoints.
• S3-Compatible: Uses HMAC authentication with Access Key ID, Secret Access Key, and Region. Works with S3-compatible services such as AWS S3, GCP HMAC, and MinIO.

Configure via UI

1. Go to Settings → Integrations → Sourcemap Storage.
2. Enter your URL Template and choose Auth Type (Bearer or S3).
3. Provide credentials:
   • Bearer: Token
   • S3: Access Key ID, Secret Access Key, Region (default us-east-1)
4. Toggle Enabled on. Initial enablement requires all required fields; afterwards you can rotate credentials without toggling off.
5. Save. Secrets are masked on subsequent reads, but preserved if not re-sent.

Using metadata key:value pairs (tags)

• Provide tags when starting agents, e.g. --tag build:1.2.3 --tag commit:abc123.
• Reference them in templates with {tag:build}, {tag:commit}, or {tag:*}. Missing required tags cause fetch to fail with a clear error.

Troubleshooting

• "Credentials are required": Send token (bearer) or both S3 keys on first setup.
• "Only HTTPS URLs are allowed": Use https:// or switch to s3:// with authType: "s3".
• 401/403/404 responses are mapped to user-friendly errors in the fetch endpoint; check credentials, permissions, or template path.
• "Required tag ... not found": Add the tag to the agent or adjust the template.

Checklist for a working setup

• URL template resolves with your app name and tags.
• Auth type matches the endpoint (bearer for HTTPS, s3 for S3 URLs).
• Credentials saved (and rotated as needed).
• Config enabled.
• External endpoint returns a zip that contains valid .map files.