Skip to main content

Sentry Integration

Align reads production errors from Sentry and links them to the Align entries they belong to. Each workspace brings its own Sentry access: a key from its own Sentry organization, or an installation of Alignsoft, the Sentry integration Align publishes. Align only reads from Sentry; it never writes to your Sentry data.

What it does​

  • Errors linked to entries. Sentry issues are matched to Align entries, so an error leads to the work that caused or fixes it. See How errors reach entries.
  • Production health on the project. The project dashboard shows unresolved production errors and, where Sentry reports it, the crash-free session rate.
  • Release readiness. A release's readiness strip shows the crash-free rate Sentry reports for the matching release.
  • Reports. Max, Align's assistant, can build report sections from your Sentry data: top production errors, new vs. regressed issues, crash-free and error trend, errors by release, and a production incident report. See Max.

Clients do not see Sentry detail: the Error Monitoring card on an entry is hidden from the client role.

Requirements​

  • An Align workspace at app.alignsoft.us.
  • The Admin role in that workspace.
  • Permission in your Sentry organization to create an internal integration (or to install Alignsoft).

Connecting with your own key​

This is the usual way in. It works for sentry.io and for self-hosted Sentry. Any number of Align workspaces can each use a key of their own from the same Sentry organization.

  1. In Sentry, go to Settings → Custom Integrations and create an internal integration. Name it "Align".
  2. Give it Read access to Organization, Project, Issue & Event and Release. Align needs nothing more.
  3. Save it, then copy its Token and its Client Secret.
  4. In Align, go to Settings → Integrations. Under Developer Tooling, click Configure on the Sentry row (or turn on its switch).
  5. Enter the Sentry organization slug (from sentry.io/organizations/<slug>/), the Token, and the Client secret (for the webhook). For self-hosted Sentry, also enter the Self-hosted Sentry URL (optional). Click Connect.
  6. Align checks the key at once: that Sentry accepts it, and that it can read the organization, its projects, and a project's issues and releases. If a permission is missing, the card names it. Add it in Sentry, then click Save and check.
  7. Webhook. On the same card, under Webhook, click Make the address and copy the address Align shows. Align shows it once. In Sentry, open the same integration, paste it as the Webhook URL, tick the issue events, and save. New and changed issues then reach Align as they happen. Without the webhook, Align does not pick up new issues as they happen.
  8. Map each Align project to its Sentry project. Use Project mappings on the Sentry card, or the Sentry — production errors section in the project's own Integrations tab.

The token and client secret are stored encrypted (AES-256-GCM) and are never shown again. To change the key, paste a new one and click Save and check; leaving the token blank keeps the stored one. To replace the webhook address, for example if it leaked, click Replace the address. The old address stops working at once.

Installing Alignsoft instead​

On sentry.io you can install Alignsoft instead of making a key. On the Sentry card, open Or install Alignsoft from Sentry and click Install from Sentry. Choose your Sentry organization and approve the installation in Sentry. Sentry sends you back to Align, which finishes the connection. No token is copied by hand, and Align refreshes its tokens itself.

A Sentry organization can install Alignsoft for one Align workspace only. If another workspace already uses your Sentry organization, connect with a key instead.

If the card says "Install is not available on this deployment", connect with a key. If Sentry says Alignsoft is installed but Align does not recognise it, click Stuck? Reset the Sentry connection. This clears Align's side and, when it can, uninstalls Alignsoft in Sentry so you can install again.

How errors reach entries​

Align matches Sentry issues to entries in two ways:

  • Exact. When a Sentry release names an entry (ALN-42 in the release), Align links that release's issues to the entry and marks the link confirmed.
  • Suggested. When a Sentry release matches an Align release, Align suggests the issue for that release's entries, with a confidence score.

Each entry's Error Monitoring card lists its linked issues, with event and user counts and the Sentry release, and a Suggested correlations list. Admins and managers can Confirm or Dismiss each suggestion. Dismissing a suggestion on one entry hides it there only.

Align does not create entries from Sentry issues. Matching runs when an issue webhook arrives for the projects bound to that connection.

When Sentry stops accepting the connection​

If Sentry rejects Align's key or token, for example because the key was revoked or an installation's authorization expired, the Sentry card shows the reason in red and the connection is marked Not working. Align cannot read from Sentry until it is fixed. Paste a new key (or reinstall Alignsoft) and click Check again.

If the key works but lacks one permission, for example Release read, the card shows a warning naming what Sentry refused. Everything else keeps working. Add the permission in Sentry and click Check again to clear it.

Webhooks​

Webhooks are signature-verified.

  • With your own key, Sentry signs each delivery with your integration's client secret. Your webhook address reaches only the projects bound to your connection.
  • With Alignsoft, Sentry signs with Alignsoft's secret.

Issue events refresh the error matching for the bound projects. An Alignsoft uninstall in Sentry disables the Align connection immediately.

Disconnecting​

  • In Align: on the Sentry card, click Disconnect. Align removes the stored credentials and the project mappings. For an Alignsoft installation, it also tries to uninstall Alignsoft in Sentry.
  • In Sentry: delete the internal integration (its token stops working), or uninstall Alignsoft. An Alignsoft uninstall disables the Align connection automatically.

Error links already made stay on your entries.

Support​

Questions or issues: support@alignsoft.us. We aim to respond within one business day.

Changelog​

  • 2026-10 — Support questions now go to support@alignsoft.us.
  • 2026-10 — Connecting with your own Sentry key is the main path, checked for each permission on save, with a webhook address per connection. A connection Sentry stops accepting shows as not working.
  • 2026-07 — Initial public release: Alignsoft install, issue webhooks, error-to-entry matching, and production-health reporting.