Skip to content
SHC Docs

GlitchTip

These answers used to sit on this app’s store listing. They moved here on 2026-08-17: a shopper deciding whether to install is not reading six hundred words of Q&A, and the listing page is the pitch. The knowledge is no less true for being off the storefront: it is the part you want before you commit, which is what a guide is for.

It implements the ingest protocol your SDK speaks, which is the part your code depends on. It is not a fork of Sentry and this page does not claim feature parity with it. It claims the protocol, and that claim is what makes the switch a one-line change.

Can it publish a status page my customers can open?

Section titled “Can it publish a status page my customers can open?”

No. It checks uptime internally and publishes nothing shareable. That was measured at the pinned version and re-confirmed at the next one, and it is recorded in the package, so the uptime package in this catalogue keeps that job.

No. GlitchTip is MIT and the key upstream offers is voluntary support rather than a feature gate: the single sign-on you configure here is the same MIT code everybody else runs.

A bound consumer gets its DSN through the sentry socket. Clients that bind nothing, like a web app or a CLI that only needs a DSN at build time, get theirs from the projects var instead. It’s a list of names, each matching [A-Za-z0-9][A-Za-z0-9_-]*:

vars:
projects:
- portal-web
- shc-cli

On every install and update the grant-sentry-projects hook creates any missing project and ingest key for each name in one organization, the slug org names (the tenant name when unset), with the same rows and the same name matching the socket uses, so a rerun creates nothing new. It logs granted <name> and never prints a DSN. A name outside the charset fails the hook before it touches the database. Dropping a name deletes nothing.

To read the DSNs back, run the on-demand job:

Terminal window
shc job run list-sentry-projects -s <stack> --wait

It prints one name=dsn line per declared name that has a project, and nothing else on stdout. It creates nothing: a name the hook hasn’t reached yet is reported on stderr instead. A DSN is a public ingest identifier, safe to ship inside a client. It still lets whoever holds it send events, so the job declares sensitive_output: the run’s row keeps its output sealed, and reading it takes stack:manage.

A tool that only reads issues, such as a dashboard tile, needs an API token, not a DSN. When projects names anything, the glitchtip-read-token hook runs after grant-sentry-projects and keeps one for it:

  • a passwordless service user, [email protected], joins that organization as a plain member;
  • that user holds exactly one API token, with org:read, project:read and event:read and no other scope, so it can list and read issues and events but a write such as PUT /api/0/issues/<id>/ answers 403;
  • the token lives in the deployment vault as hook_apiTokens.readOnly.

A redeploy keeps a sealed token that still authenticates as that user and strips any scope or role added by hand. A token that no longer authenticates (deleted, or its user deactivated) is replaced, and the user’s other tokens are deleted, so revoking one in the UI takes effect on the next deploy. The hook prints the token only inside its seal marker, which SHC blanks before it stores the job’s output.

Read the issues of project drover-app in organization bitspur with it like this:

Terminal window
curl -H "Authorization: Bearer $TOKEN" https://errors.example.com/api/0/projects/bitspur/drover-app/issues/

A triage token for tools that resolve issues

Section titled “A triage token for tools that resolve issues”

A tool that resolves or ignores issues, such as an agent working its error queue, needs a token that can write events. The glitchtip-triage-token hook runs after glitchtip-read-token and keeps it the same way, for its own passwordless member, [email protected]:

  • the token holds exactly org:read, project:read, event:read and event:write;
  • it reaches every project in the organization org names, because GlitchTip scopes a token by its user’s membership, not by project;
  • event:write is GlitchTip’s one write scope for issues, so the token can delete an issue as well as resolve or ignore it, and it can’t change a project, an alert or a member;
  • the token lives in the deployment vault as hook_apiTokens.triage.

Resolve an issue with it like this:

Terminal window
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status": "resolved"}' https://errors.example.com/api/0/issues/<id>/

The nightly maintenance task, at 05:00 UTC, deletes what is older than the retentionDays vars. Each one defaults to 90 days:

varwhat it boundsGlitchTip setting
retentionDays.eventserror events, their tags and aggregates; an issue unseen that long goes 7 days laterGLITCHTIP_EVENT_RETENTION_DAYS
retentionDays.transactionsperformance transactionsGLITCHTIP_TRANSACTION_RETENTION_DAYS
retentionDays.logslog recordsGLITCHTIP_LOG_RETENTION_DAYS
retentionDays.uptimeChecksuptime check resultsGLITCHTIP_UPTIME_RETENTION_DAYS
retentionDays.filesuploaded source maps and debug filesGLITCHTIP_FILE_RETENTION_DAYS

Events stay in PostgreSQL for their whole life. The package never turns on GlitchTip’s DuckDB cold storage.

Bind an s3 edge, or set s3.endpoint, and GlitchTip keeps uploaded source maps and debug files in the bucket through its own django-storages S3 backend instead of on the glitchtip-uploads volume. The bucket is s3.bucket, or <stack>-<environment> when that’s blank. Unbound, nothing changes.

Moving to a bucket doesn’t copy what’s already on the volume, so bind it before anything uploads, or copy the files across first.

GlitchTip 6.2.5 has no per-key or per-project event cap. A key’s rate-limit fields are stored and shown in the UI, but ingest doesn’t read them, so a client that floods the ingest endpoint has to be stopped in front of GlitchTip.