Linear Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy for issue-tracker integration. The package covers the expensive, undifferentiated parts of a Linear integration: OAuth 2.0 with PKCE, lock-protected token refresh, encrypted personal API keys, queued delivery with retries/backoff, and idempotent creation that adopts an issue after a timed-out request instead of duplicating it. That is weeks of work you can redirect to product surface area.
• Feature bets on in-product feedback capture. CreatesLinearIssues turns any Eloquent model into an issue source on created / updated / deleted. This unlocks roadmap items like "report this record," support-ticket escalation, QA/bug intake from internal tools, and error-to-issue pipelines — without designing an integration per feature.
• Self-serve onboarding vs. hand-holding. A ready-made /linear configuration page lets a user or team connect their own workspace and choose team, project, status, assignee, labels and priority. That's a support-cost decision: ship the bundled page now, revisit only if the flow measurably hurts conversion.
• Noise control as a product lever. The automatic vs. manual sending toggle (plus per-model linearEvents() and customizable title/description/comments) is how you decide whether the feature is "fire and forget" or "review before filing." Default it deliberately — automatic-on-updated is the fastest way to generate complaints.
• UI scope decision. Everything is optional: disable the UI, disable OAuth or API route groups, embed <x-linear::settings /> in your own layout, or Linear::ignoreRoutes(). The headless Actions and typed DTOs (Team, Project, WorkflowState, Member) plus docs/custom-ui.md mean "use the plumbing, own the UI" is a supported path rather than a fork.
• Data model commitment. The trait adds linear_issue_url, linear_issue_identifier and linear_sync_status columns and ships migrations — a schema decision to schedule, not a drop-in.
• Test strategy and CI cost. Linear::fake() with assertIssueCreated() and failWith() means no Linear sandbox workspace and no HTTP stubbing in your test suite; this lowers the cost of the feature enough to change whether it's worth building at all.
• Stability signal for planning. 1.0.0 implies a semver commitment and an API you can plan a quarter around. The explicit upgrade note (re-publish published assets on every update) is a standing maintenance line item to budget.

When to Consider This Package

Adopt when:

• You are on PHP 8.3+ and Laravel 12 or 13. This is a hard gate, not a preference — on older Laravel this package is not an option, and adopting it may force a framework upgrade you'd otherwise defer.
• Linear is your committed tracker for the next 12+ months. The package is Linear-specific; there is no adapter abstraction.
• You want per-user or per-team workspace connections (the HasLinearConnection owner model) rather than one shared org-wide token.
• You want issue creation to be non-blocking and non-fatal — lifecycle hooks report errors rather than throw, so a Linear outage never breaks a customer's save. Confirm this matches your expectations; some teams want hard failure.
• You accept a community-maintained, unofficial dependency (explicitly not affiliated with or endorsed by Linear) and can absorb single-maintainer risk, or can vendor/fork it.
• You can own the operational tail: adding vendor:publish --tag=linear-assets --force to post-update-cmd, keeping published JS/CSS in sync with the package version, and adding avatar hosts to img-src if you run a strict CSP.

Look elsewhere (or build) when:

• You need bidirectional sync. This release is outbound: it creates issues and comments and tracks delivery status (linear_sync_status), not Linear workflow state flowing back into your app. If "issue closed → update my record" is on the roadmap, that's custom work on top.
• You are on Laravel ≤ 11 or PHP < 8.3 and won't upgrade.
• You need multi-tracker support (Jira, GitHub Issues, Linear) behind one interface, or a vendor with an SLA and enterprise support terms.
• You run SQL Server and need model-less comment rows (documented limitation), or you soft-delete models while syncs are pending — those syncs fail with "no longer exists."
• You can't publish migrations: unpublishing is a documented footgun that logs a query error on every save of a linked model.

How to Pitch It (Stakeholders)

For executives: This is a stable 1.0 release of a Laravel package that connects our app to Linear the way Laravel Spark handles billing — add a trait, users connect their workspace on a built-in settings page, and issues are filed automatically from model events. It replaces the part of the build we'd never differentiate on: OAuth, token refresh, secure key storage, retry logic and duplicate prevention. Cost is a Composer dependency and a small, known maintenance line item; the trade-off is that it's an unofficial community package from a single maintainer, so we should pilot it on an internal or low-blast-radius surface before making it customer-facing, and be prepared to fork it.

For engineering: PHP 8.3+, Laravel 12–13, composer require plus two publish steps and a migrate. Reliability is designed in: queued jobs with retries and backoff, idempotent creation that adopts an issue after a timeout rather than duplicating, hooks that report rather than throw, failed syncs surfaced on the config page with a retry button, and LinearIssueCreated / LinearIssueFailed / LinearCommentDelivered events to hook into. Linear::fake() covers app tests, and the package itself is PHPStan level 9 with strict TypeScript at 100% coverage across PHP 8.3/8.4 and Laravel 12/13. Two things to plan for: published assets must be re-published after every update (put it in post-update-cmd), and the scope is outbound only — no reading Linear state back into our models.

Ask: approve a scoped pilot on an internal surface, with a decision checkpoint after one release cycle covering (a) issue volume/noise from automatic sending, (b) whether the bundled config page is good enough or we go headless, and (c) maintainer responsiveness as a proxy for dependency risk.