Linear Sdk Laravel Package

Technical Evaluation

Architecture fit

• The package integrates at the Eloquent lifecycle layer (created/updated/deleted) via the CreatesLinearIssues trait, plus a workspace-owner trait (HasLinearConnection). This is the Laravel Spark billing pattern applied to issue tracking: opt-in per model, no changes to controllers or domain services. That is a low-friction architectural fit and keeps the integration declarative rather than scattered through application code.
• The unit of adoption is a model, not an application. A TPM can scope a pilot to one or two high-value models (e.g. BugReport, SupportTicket) and expand from there, which is exactly the kind of incremental scope a roadmap needs.
• The escape hatches matter for architecture review: every surface is optional (UI, OAuth routes, API routes can be disabled), a headless Actions + DTO layer exists with a documented HTTP contract, and the bundled Blade component can be embedded in an existing layout. This means the package can be used as a backend sync engine only, with a product-owned UI on top. That preserves design control and avoids shipping a third-party-branded page.

Integration feasibility

• Hard prerequisites are the first gate: PHP 8.3+ and Laravel 12 or 13 only. Any application on Laravel 10/11 or PHP 8.1/8.2 cannot adopt without a framework upgrade. The TPM should treat the Laravel upgrade as a dependency in the same roadmap, not a footnote.
• Installation is three artisan commands plus config. Real effort sits in: registering a Linear OAuth app (client ID/secret, redirect URIs per environment), deciding personal-API-key vs OAuth per tenant, and mapping Linear teams/projects/statuses to the product's model taxonomy.
• Linear::fake() with assertIssueCreated() and failWith() is a genuine feasibility win — the integration can be covered in CI without network access, so acceptance criteria are testable and the QA cost is bounded.

Technical risk

• Vendor risk (primary): unofficial, community-built, single-maintainer, with an explicit non-affiliation disclaimer. There is no Linear support contract, no SLA, and the Linear GraphQL/API surface can change under it. Mitigation: keep the trait surface thin, rely on the emitted events and the documented HTTP contract so the package is replaceable, and avoid letting linear_sync_status become a source of truth.
• Data egress risk: model attributes (titles, descriptions, comments) are transmitted to a third-party SaaS. Privacy/security review is mandatory: classify which models are eligible, forbid PII-bearing models, and confirm DPA/retention posture with Linear. This is the gating risk, not the code.
• deleted event handling is a decision, not a default. Mapping deletions to Linear issues can close or archive work items unintentionally. Require an explicit per-model allowlist of linearEvents() reviewed by the product owner.
• Silent-failure posture: lifecycle hooks never throw — errors are reported and surfaced as failed syncs. Good for app stability, but it means "no error" does not mean "synced." Observability is a prerequisite, not a nice-to-have.
• Lock-protected token refresh implies a shared cache/lock store (Redis or database). Single-server or array cache deployments will misbehave at refresh time.

Key questions

1. Which models are in scope for v1, and do any of their fields contain customer PII or regulated data?
2. What is the Linear workspace topology — one shared workspace, or per-customer/per-team OAuth connections? This determines whether HasLinearConnection sits on User or Team and drives the entire data model.
3. Is the Linear relationship one-way (Laravel → Linear) only? The package does not claim inbound sync; confirm no stakeholder expects bidirectional status mirroring.
4. Which environments get real Linear credentials, and will sandbox issues pollute the production workspace?
5. Who owns the error-reporting sink (Sentry/Telescope/log channel) that receives swallowed sync failures, and what is the alert threshold?
6. Does a strict CSP exist today? If so, avatar host allowlisting in img-src is a pre-launch task with a visible UI degradation if missed.
7. Is deleted → Linear behavior in scope for any model?

Integration Approach

Stack fit

• Fits cleanly into a modern Laravel 12/13 codebase already using queues, Redis, and Vite. The compiled assets ship with the package, so no Node toolchain is required — that removes a common blocker for teams without a frontend build pipeline.
• The Alpine + TypeScript configuration page will look and behave like a first-party page; the team should still decide whether to ship it as-is at /linear, embed <x-linear::settings /> in an existing settings layout, or suppress it entirely and build a bespoke UI against the Actions/DTOs.

Migration path

• Greenfield-friendly: publish migrations, migrate, add traits, done. For existing apps, sequence as (1) framework/PHP upgrade if needed, (2) OAuth app registration and secrets management, (3) migration publish, (4) trait on one model behind a feature flag, (5) UI.
• Note that migrations land in the host application's database/migrations directory. The package owns no schema of its own at runtime — the app does. Establish a convention early (naming, no edits post-deploy) before the migration count grows.
• Plan a rollback that is data-safe: disabling the trait stops new syncs, but rows already carrying linear_issue_url/linear_sync_status remain. Decide whether to leave the columns (harmless) or back them out in a later release.

Compatibility

• Version matrix is narrow and explicit: PHP 8.3/8.4 × Laravel 12/13, tested at 100% coverage under PHPStan level 9. That is unusually strong quality signalling for a community package and lowers the "will it break in CI" risk considerably.
• Known platform caveats to check against the target stack: SQL Server has a constraint on comment rows without a source model (MySQL/PostgreSQL/SQLite unaffected); soft-deleted models with in-flight syncs fail with "no longer exists."
• 1.0.0 marks the start of semver guarantees, so the public API (traits, Actions, DTOs, events, Linear::fake()) should be treated as stable from here.

Sequencing

1. Security/privacy review and Linear DPA confirmation (blocking).
2. PHP/Laravel upgrade if not already on 12/13.
3. Register OAuth app; decide OAuth vs personal API key per tenant; wire secrets per environment.
4. Publish migrations; verify in staging that the "unpublished migrations → query error on every save" trap is avoided.
5. Enable on one low-risk model with linearEvents() restricted to created only; wire the error sink and LinearIssueFailed alerting.
6. Ship the configuration UI (or embedded component) and add vendor:publish --tag=linear-assets --force to post-update-cmd before the first deploy that touches the UI.
7. Expand to additional models and event types after a two-week soak.

Operational Impact

Maintenance

• The published JS/CSS live in public/ and are not updated by composer update. Re-publishing after every package update is a manual step that will be forgotten. Mandate the post-update-cmd automation in the same PR that introduces the package — this is the single most likely source of "the settings page is broken/stale" tickets.
• Recurring cost is low but non-zero: watch releases for Laravel-major compatibility and Linear API changes. Assign a named owner and a monthly check rather than assuming passive stability from a 1.0.0 tag.

Support

• Two support surfaces emerge: (a) internal — "my issue didn't appear in Linear," answered by the failed-sync list on the config page and the retry button; (b) end-user — connecting a workspace, choosing team/project/status/assignee/labels.
• Because errors are reported and not thrown, the support workflow depends entirely on the error sink being wired and monitored. Without it, failures are invisible until a user notices a missing issue.
• Document the signed-out redirect (configurable login route, default login) and the configurable Back link (Linear::backUsing(), default /dashboard) — both are defaulted to Laravel conventions and will be wrong for apps that differ.

Scaling

• Issue and comment sends run on queued jobs with retries and backoff, so throughput scales with worker capacity rather than request latency. Provision workers and monitor queue depth; a burst of model saves becomes a burst of Linear API calls against workspace rate limits.
• Idempotent creation (a timed-out request adopts the issue Linear already created rather than duplicating) is the key scaling safeguard — without it, retries would pollute the workspace and erode trust in the integration. Verify this behavior explicitly in the pilot.
• Token refresh is lock-protected, which requires a real shared store. Confirm Redis/database cache in all environments, including staging, before load testing.

Failure modes

• Silent sync failure (most common): save succeeds, issue never created. Detect via LinearIssueFailed event → alert; remediate via retry button or retryLinear().
• Unpublished migrations: every save of a linked model logs a query error while the save itself succeeds — noisy but non-fatal, and a strong argument for verifying migrations in staging.
• Soft-delete race: model soft-deleted while a sync is pending → job fails with "no longer exists." Expected; suppress alerting on this specific error class or accept known-noise.
• Token expiry/revocation: user revokes the Linear app or the token is invalidated → all syncs for that owner fail. Surface as a "reconnect" state in the UI.
• CSP blocking avatars: initials fallback renders, so it degrades gracefully — cosmetic only.
• Queue outage: syncs accumulate silently; the model's linear_sync_status is the only in-app signal. Alert on queue depth, not just on failures.
• Deletion mapping mistakes: if deleted is enabled and misconfigured, Linear issues are closed/archived unexpectedly — a one-way, user-visible error. Keep the event allowlist minimal and reviewed.

Ramp-up

• Engineer: roughly 1–3 days for install, OAuth wiring, migration and trait on a first model, plus test coverage using Linear::fake().
• Frontend/product: 1–2 days to decide on bundled vs embedded vs custom UI and to map teams/projects/statuses.
• Security/privacy review: the long pole — schedule it first, not last.
• End-user ramp is light: the shipped configuration page is self-service, accessible, and visually consistent with Linear. Expect a short enablement note ("connect your workspace, pick a team and default state, choose automatic or manual sending") rather than a training program.
• Success measures for the pilot: percentage of eligible model creations that produce a Linear issue within N minutes, failed-sync count trending to zero, retry-button usage, and zero duplicate issues from retries.