Chom-Bev-e-Brezhoneg/docs/sentry-glitchtip.md

Crash reporting — Sentry SDK on GlitchTip

Chom Bev reports crashes and handled errors with the Sentry Kotlin Multiplatform SDK, but sends them to GlitchTip instead of Sentry. GlitchTip is an open-source, Sentry-API-compatible backend, so the Sentry SDKs and glitchtip-cli work against it unchanged — only the DSN (and the CLI's url) point somewhere else.

Our instance is the hosted EU one: https://eu.glitchtip.com.

SDK	io.sentry.kotlin.multiplatform (see sentry in gradle/libs.versions.toml)
Gradle plugin	io.sentry.kotlin.multiplatform.gradle, applied in shared/build.gradle.kts
iOS native dependency	sentry-cocoa via Swift Package Manager, declared in the Xcode project
Initialisation	initializeSentry() in shared/src/commonMain/kotlin/bzh/ajaury/chombev/SentryHelper.kt
Called from	ChomBevApp.onCreate() (Android), AppDelegate.application(_:didFinishLaunchingWithOptions:) (iOS)

There are two distinct pieces of configuration, and they are easy to confuse:

1. The DSN — where the app sends events at runtime. Injected at build time from local.properties. See Runtime configuration.
2. The auth token — how your machine or CI uploads debug symbols to GlitchTip. Stored in .sentryclirc. See CLI configuration.

Neither is committed.

---

1. Runtime configuration — the DSN

The DSN is a write-only endpoint URL identifying the GlitchTip project. It is kept out of version control by the gwenedeg.secrets convention plugin (build-logic/src/main/kotlin/gwenedeg.secrets.gradle.kts), which reads it at build time and generates an internal BuildSecrets object into commonMain.

Setup

Add the DSN to local.properties at the repository root (this file is git-ignored):

glitchtip.dsn=https://<key>@eu.glitchtip.com/<project-id>

Find the value in GlitchTip under Settings → Projects → Chom Bev e Brezhoneg → Client Keys (DSN).

On CI, set the GLITCHTIP_DSN environment variable instead — it takes precedence over local.properties.

Behaviour when it is missing

initializeSentry() returns early when the DSN is blank, so a fresh clone builds and runs with crash reporting simply disabled. No placeholder or dummy DSN is needed.

Adding other secrets

Extend the secret(environmentVariable, localPropertyKey) helper in the convention plugin rather than hardcoding values in Kotlin sources.

---

2. CLI configuration — .sentryclirc

sentry-cli needs an auth token to upload debug symbols. It reads its settings from a .sentryclirc INI file in the current working directory (and from ~/.sentryclirc), or from environment variables.

.sentryclirc contains a credential and must never be committed. It is listed in .gitignore. Only .sentryclirc.example is versioned.

Setup

cp .sentryclirc.example .sentryclirc
chmod 600 .sentryclirc

Then edit .sentryclirc and replace the token placeholder:

[auth]
token=<your-glitchtip-auth-token>

[defaults]
url=https://eu.glitchtip.com/
org=kerlenn-sten-kidna
project=chom-bev-e-brezhoneg

• url is mandatory: without it glitchtip-cli talks to sentry.io, not GlitchTip.
• org and project are the slugs shown in the GlitchTip URLs, not the display names.

Creating the token

In GlitchTip: user menu → Profile → Auth Tokens → Create New Token. Grant it at least project:read, project:write and project:releases. Copy the token immediately — it is shown only once.

On CI

Do not write the file. Export the equivalent environment variables, sourced from your CI secret store:

export SENTRY_URL=https://eu.glitchtip.com/
export SENTRY_ORG=kerlenn-sten-kidna
export SENTRY_PROJECT=chom-bev-e-brezhoneg
export SENTRY_AUTH_TOKEN=***

Installing glitchtip-cli

curl -fsSL https://glitchtip.com/install.sh | sh  

Check that the configuration resolves:

glitchtip-cli info

It should print the GlitchTip URL and report the token as valid.

---

3. iOS Archive — uploading dSYM files

Why this is needed

A release iOS binary ships without symbol names. Without the matching dSYM, GlitchTip shows crash frames as raw memory addresses. Uploading the dSYM lets it resolve them back to function names and line numbers.

The shared Kotlin framework is linked statically (isStatic = true in shared/build.gradle.kts), so Kotlin/Native frames end up in the app's own dSYM — there is no separate framework dSYM to upload.

Prerequisites

You need glitchtip-cli installed and .sentryclirc filled in (section 2).

Upload after an archive

1. Product → Archive in Xcode.
2. In the Organizer, right-click the archive → Show in Finder.
3. Right-click the .xcarchive → Show Package Contents.
4. Upload the dSYMs folder:

cd /path/to/Gwenedeg
glitchtip-cli debug-files upload /path/to/Gwenedeg.xcarchive/dSYMs

Add --include-sources if you also want source context attached to native frames.

4. References

• Sentry — Kotlin Multiplatform SDK
• Sentry — Uploading debug symbols for Apple platforms
• Sentry — data collected by the SDK
• GlitchTip documentation
• GlitchTip CLI documentation
• Kotlin — symbolicating iOS crash reports