Skip to main content

Linear integration

Log Lens can optionally pull issues from Linear into your dashboard and mirror status changes back. It is off by default and enabled per application from Settings → Linear.

Use it to see the issues your team tracks in Linear — the ones with specific labels, or the ones assigned to you — alongside the errors Log Lens already captures, and to keep both systems in step when you triage.

What it does​

  • Pull issues that match a set of Linear labels, are assigned to you, or are assigned to specific people (optionally scoped to one team). Matching is labels OR assignee; a team key further narrows the scope.

"Assigned to me" resolves to the API key's owner, because Log Lens authenticates with a personal key and Linear evaluates "me" server-side from that key. If the key is a shared/service-account key, use the Assignees field (emails or Linear user ids) to pull issues for specific people regardless of which key is configured. Test connection shows exactly which Linear account the key belongs to.

  • Store them as issues (origin=linear) so they show up in the issue list, are filterable, taggable, and searchable like any other issue. Linear labels become Log Lens tags.
  • Link status back to Linear (optional): when you change a linear-sourced issue's workflow status in Log Lens, it comments on the Linear issue and, for terminal/started statuses, transitions its Linear state.

Priority maps to severity (Urgent→CRITICAL … None→INFO) and Linear's workflow state maps to Log Lens status on import (completed→fixed, canceled→wont_fix, started→in_progress, else open). Re-syncing refreshes the mirrored fields but never overwrites a status you changed locally.

How re-syncing avoids duplicating or clobbering anything​

Each pulled issue is stored as an ordinary error_groups row (origin=linear), keyed by a fingerprint derived deterministically from the Linear issue's id (sha256("linear|" + linearIssueId)) — not from its title or content. Re-running sync looks up that same fingerprint: if it already exists, the row is updated in place (title, severity, description, labels/tags) rather than creating a duplicate, no matter how many times you sync or how much the Linear issue's text has changed since.

One field is deliberately not refreshed on update: status. Once you've changed a linear-sourced issue's workflow status locally (or it's been transitioned via write-back), that status is authoritative — a re-sync will never silently flip it back to match Linear's current state. If you want Log Lens's status to follow Linear again, that has to happen through the write-back direction (below) or a manual status change.

This also means Log Lens never talks to the byte-mirroring connector pipeline for Linear issues — connectors are built for append-only log files; Linear issues are structured records fetched via GraphQL, so they get their own simpler upsert instead.

Setup​

  1. In Linear, create a personal API key (Linear → Settings → API → Personal API keys).
  2. In Log Lens open Settings → Linear, paste the key, add the labels you care about and/or toggle Assigned to me, then enable the integration.
  3. Click Test connection to confirm, then Sync now to pull.

Keeping the key secure (enterprise)​

  • Preferred: provide the key as the LOG_LENS_LINEAR_API_KEY environment variable (or .env). It is then never written to the database and the UI field is locked.
  • Otherwise the UI-entered key is encrypted at rest using LOG_LENS_SECRET (Laravel deployments fall back to APP_KEY). Without a deployment secret the key is stored unencrypted and the settings panel warns you.

Log Lens never displays a stored key back to the browser.

Staying in sync​

  • Manual: the Sync now button, or php bin/linear-sync.php --app={id}.
  • Scheduled: on Laravel, php artisan log-lens:linear-sync --app={id} — schedule it, e.g. ->everyFifteenMinutes().
  • Real-time (webhook): create a Linear webhook pointing at …/?api=linear-webhook&app={id} — inside a Laravel app, point it at the dedicated route …/log-lens/linear-webhook?app={id} instead, which sits outside the host's access gate and CSRF check (both would reject Linear's sessionless delivery). Set a signing secret in both Linear and the Linear settings panel. Log Lens verifies the Linear-Signature HMAC over the raw body and re-syncs on each event.
  • Linear API endpoints
  • Connectors — the separate system for mirroring log files
  • Alerting — rules can match linear-sourced issues the same as any other, since they're ordinary issues once pulled in