.png)
Linear Integration Guide
Connect Linear with enterprise systems through its GraphQL API, selected webhook events, OAuth 2.0, API keys, and orchestrated Martini workflows.
Linear integration options at a glance
Linear’s primary integration surface is a GraphQL API for querying workspace data and executing mutations against issues, projects, teams, cycles, comments, and related objects. Selected resources also emit webhook events, which Martini can receive through an API, validate, deduplicate, and process asynchronously. OAuth 2.0 supports installed or user-authorized applications, while API keys suit controlled internal integrations. Cursor-based pagination enables scheduled incremental synchronization, and Linear supports file uploads and attachments for supported objects. Martini can orchestrate these mechanisms, apply business rules, map GraphQL responses, persist checkpoints, and expose normalized APIs to downstream systems.
| Integration point | Supported by Linear? | Common use cases | How Martini supports it |
|---|---|---|---|
| GraphQL APIs | Yes | Linear’s primary public API supports queries and mutations for Issues, Comments, Projects, Teams, Cycles, Labels, and related workspace objects. | Martini workflows can construct GraphQL queries or mutations, authenticate with an API key or OAuth access token, map responses, and apply validation, retry, and logging logic. |
| Webhooks | Yes | Linear sends webhook notifications for selected resources and event types, including Issues, Comments, Projects, Project updates, Cycles, Users, and Labels. | Martini can expose an API endpoint to receive events, validate Linear signatures, deduplicate notifications, retrieve the current object when necessary, and invoke downstream workflows. |
| Authentication | Yes | Linear supports bearer-token API keys for controlled internal integrations and OAuth 2.0 for applications acting on behalf of users or workspaces. | Martini can store credentials securely, configure authenticated API calls, limit OAuth scopes, and separate environment-specific configuration from workflow logic. |
| Cursor-based pagination | Yes | Linear collection queries use cursors to retrieve Issues, Comments, Projects, and other collections incrementally. | Scheduled Martini workflows can persist cursors or checkpoints, process bounded pages, recover failed pages, and continue synchronization without assuming one request contains all data. |
| File and attachment APIs | Yes | Linear supports file uploads and attachments associated with supported objects such as Issues. | Martini can orchestrate file retrieval, upload processing, and attachment association while applying bounded-memory handling and explicit failure recovery. |
| Bulk and asynchronous APIs | Not confirmed | A separate general-purpose bulk or asynchronous import API was not confirmed; larger jobs should use controlled batches of GraphQL requests and mutations. | Martini can schedule and batch GraphQL operations, limit concurrency, persist progress, and retry transient failures without claiming a dedicated Linear bulk API. |
| Database access | No | Linear does not expose direct database access as a supported integration mechanism. | Martini can query Linear through GraphQL and write normalized results to a supported database, keeping persistence in the integration layer. |
How Linear exposes data and business events
Linear GraphQL API
Linear’s GraphQL API is the primary integration mechanism for reading workspace data and creating, updating, or deleting supported objects. Queries and mutations can cover Issues, Comments, Projects, Teams, Cycles, Labels, and related resources, subject to authentication and permissions.
Martini implementation pattern
Martini workflows build the required GraphQL document and variables, authenticate with an API key or OAuth access token, submit the request, validate the response, and map the result into a target application, database, or Martini API response. Query size and field selection should be controlled to manage complexity and rate limits.
Implementation sequence
Linear Webhooks
Linear webhooks provide notifications for selected resources and event types, including Issues, Comments, Projects, Project updates, Cycles, Users, and Labels. They are not a universal notification stream for every Linear change.
Martini implementation pattern
A Martini API receives the webhook, validates the Linear signature, checks the event and resource identifiers, and returns promptly. A workflow then processes the event asynchronously and can retrieve the latest object through GraphQL when the notification does not contain a complete representation.
Implementation sequence
Linear Pagination
Linear uses cursor-based pagination for collection queries. Pagination is important for scheduled reconciliation of Issues, Comments, Projects, Cycles, and other collections, especially when a workspace exceeds one response page.
Martini implementation pattern
Martini schedules a workflow that reads a stored cursor or checkpoint, requests a bounded page, processes the results, and persists the next cursor only after successful downstream handling. The workflow can recover a failed page and continue without assuming a static collection.
Implementation sequence
Linear File Uploads
Linear supports file uploads and attachments for supported objects. The upload process may involve obtaining an upload target and then associating the resulting attachment with an Issue or another supported object.
Martini implementation pattern
Martini coordinates file retrieval from a source system, upload preparation, transfer, and object association. The workflow should follow Linear’s current upload sequence and isolate large-file handling from ordinary object synchronization.
Implementation sequence
Common Linear integration patterns
Pattern 1: Synchronize support tickets to Linear Issues
When to use this pattern
Use this pattern when customer support teams need to escalate selected Zendesk or Intercom conversations into engineering work while preserving the originating ticket or conversation reference. Routing can depend on product area, severity, team, or customer impact.
Integration direction
Example Mapping
| Linear Field | Canonical Field | Target Field |
|---|---|---|
| ticket.id | sourceReference | Issue.externalReference |
| ticket.subject | title | Issue.title |
| ticket.description | description | Issue.description |
| ticket.priority | priority | Issue.priority |
Martini implementation pattern
A Martini workflow receives a source event, resolves the Linear Team and Project, checks a durable source-to-Issue mapping, and executes a GraphQL mutation only when no existing Issue is mapped. It applies status and priority rules, stores the resulting Linear identifier, and retries transient failures without creating duplicates.
Martini capabilities used
- workflows
- API consumption
- GraphQL API orchestration
- data mapping
- business rules
- error handling
Pattern 2: Coordinate GitHub development status with Linear
When to use this pattern
Use this pattern to connect repository activity, pull requests, and development status with Linear Issues. Stable repository and pull request identifiers should be used for correlation rather than matching titles alone.
Integration direction
Example Mapping
| Linear Field | Canonical Field | Target Field |
|---|---|---|
| pull_request.number | developmentReference | Issue.externalReference |
| pull_request.title | developmentTitle | Issue.title |
| pull_request.state | developmentStatus | Issue.statusContext |
| repository.full_name | repositoryReference | Issue.description |
Martini implementation pattern
Martini consumes GitHub events or scheduled API data, resolves the related Linear Issue through stored identifiers, and applies explicit mappings for status, links, and repository metadata. Linear webhook events can drive reverse notifications, while idempotency and ordered processing protect against repeated or out-of-order events.
Martini capabilities used
- event-driven workflows
- API consumption
- data mapping
- correlation and deduplication
- conditional routing
- retry handling
Pattern 3: Publish scheduled Linear project reporting
When to use this pattern
Use this pattern when product or engineering leaders need periodic reporting on Projects, Cycles, Issues, Users, and Project updates in a warehouse, spreadsheet, or internal reporting service.
Integration direction
Example Mapping
| Linear Field | Canonical Field | Target Field |
|---|---|---|
| project.id | projectId | reporting.project_id |
| project.name | projectName | reporting.project_name |
| cycle.startsAt | cycleStart | reporting.cycle_start |
| issue.state.name | issueStatus | reporting.issue_status |
Martini implementation pattern
A scheduled Martini workflow reads a persisted cursor, retrieves bounded GraphQL pages, normalizes nested project and issue data, and writes results to the reporting destination. It respects rate and complexity limits, persists progress only after successful writes, and supports recovery from a failed page.
Martini capabilities used
- scheduled workflows
- GraphQL API consumption
- cursor persistence
- data transformation
- batch processing
- monitoring and error handling
Pattern 4: Create Linear Issues from engineering incidents
When to use this pattern
Use this pattern when Sentry or another incident workflow should create a traceable Linear Issue containing severity, environment, error details, and a link to the originating incident.
Integration direction
Example Mapping
| Linear Field | Canonical Field | Target Field |
|---|---|---|
| event.issue.id | incidentReference | Issue.externalReference |
| event.message | incidentSummary | Issue.title |
| event.environment | environment | Issue.description |
| event.level | severity | Issue.priority |
Martini implementation pattern
Martini receives the incident event, derives a stable idempotency key, applies severity and team-routing rules, and invokes a Linear GraphQL mutation. It stores the Linear Issue ID and can process later Linear webhook events to update Sentry, Slack, or another incident service. Transient API failures are retried with bounded backoff.
Martini capabilities used
- webhook and event processing
- GraphQL mutations
- business rules
- data mapping
- idempotency
- retry and error handling
Applications commonly integrated with Linear
Linear is commonly connected with engineering, collaboration, support, design, and incident-management products. These integrations can synchronize selected work items, create references between systems, and distribute status or notification events without requiring full replication of every object.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| GitHub | Synchronize repositories, pull requests, development status, and engineering work with Linear Issues. | GitHub → Martini → Linear | Receive GitHub events or poll selected development data, match using stable repository and pull request identifiers, then create or update Linear Issues through GraphQL mutations. Linear webhook events can be routed back to GitHub-related workflows when status coordination is required. |
| GitLab | Connect merge requests and repository activity with Linear planning and issue tracking. | GitLab → Martini → Linear | Consume GitLab events or API responses, resolve the related Linear Team and Issue, apply explicit status and reference mappings, and execute controlled GraphQL mutations with duplicate detection and retry handling. |
| Slack | Notify engineering and product teams about new Issues, status changes, Comments, and Project updates, with selected actions flowing back to Linear. | Linear → Martini → Slack | Receive selected Linear webhook events, normalize the event, apply notification rules, and call Slack APIs. For approved Slack actions, validate the request and invoke the corresponding Linear GraphQL mutation. |
| Sentry | Create or update Linear Issues from application errors and incidents while retaining incident references and severity information. | Sentry → Martini → Linear | Consume Sentry event data, derive an idempotency key from the incident or issue identifier, map severity and environment fields, and create or update a Linear Issue. Forward subsequent Linear events to the incident workflow where needed. |
| Figma | Link design files and design-related work to Linear Projects and Issues through references and metadata. | Figma → Martini → Linear | Receive or retrieve Figma file references, validate the target Linear object, and update descriptions, attachments, or metadata through GraphQL. Use links and correlation identifiers rather than assuming full object replication. |
| Zendesk | Escalate customer support tickets into engineering Issues and synchronize selected resolution information. | Zendesk → Martini → Linear | Receive Zendesk ticket events, select the Linear Team and Project using configured rules, map ticket details to an Issue, and store the Linear Issue ID against the source ticket for later updates. |
| Intercom | Convert customer conversations and product feedback into traceable Linear Issues. | Intercom → Martini → Linear | Process Intercom conversation events or scheduled retrievals, apply routing and priority rules, create a Linear Issue through GraphQL, and retain the originating conversation identifier for deduplication and status feedback. |
| Notion | Connect product documentation, planning references, and Linear Projects or Issues through links or selected synchronized fields. | Linear → Martini → Notion | Consume Linear webhook or scheduled data, transform project and issue summaries, and write approved references to Notion. Where bidirectional linking is needed, maintain durable identifiers and avoid relying on display names. |
How to build a Linear integration in Martini
Objective
Configure the Linear authentication model and environment-specific settings before building business logic.
Instructions in Martini
- Choose an API key for a controlled internal integration or OAuth 2.0 for user- or workspace-authorized access.
- Store tokens, client secrets, webhook signing secrets, and other sensitive values in secure Martini configuration.
- Request only the Linear permissions required by the workflows.
- Configure the GraphQL endpoint and any Martini API endpoint used for inbound webhooks.
Objective
Select an event-driven, scheduled, or API-led entry point that matches the synchronization requirement.
Instructions in Martini
- Use a Martini API or workflow to receive supported Linear webhook events.
- Use a scheduler for reconciliation, reporting, and cursor-based incremental retrieval.
- Use an external application event when Linear should be updated in response to another system.
- Combine webhooks with scheduled reconciliation when webhook coverage is not complete.
Objective
Obtain the current Linear object or collection with bounded, permission-aware GraphQL requests.
Instructions in Martini
- Build queries that request only required fields.
- Use the resource identifier from a webhook to retrieve the latest object when the event is incomplete.
- Use cursor-based pagination for collection synchronization.
- Resolve workspace-specific Teams, Projects, Users, Cycles, and workflow states by identifier.
Objective
Coordinate validation, correlation, transformation, target calls, and response handling in a maintainable Martini workflow.
Instructions in Martini
- Validate inbound payloads and Linear webhook signatures.
- Check event actions and durable correlation mappings before mutating data.
- Separate immediate webhook acknowledgement from longer downstream processing where appropriate.
- Route records according to team, project, priority, or source-system rules.
Objective
Convert Linear’s GraphQL structures and provider-specific values into canonical models and target payloads.
Instructions in Martini
- Map Issues, Projects, Comments, Teams, Users, and Cycles to explicit target fields.
- Handle nullable GraphQL fields and team-specific workflow states.
- Normalize identifiers, timestamps, links, priorities, and status values.
- Apply source-to-target transformations without relying on display names as durable keys.
Objective
Apply business rules and write results to Linear or downstream systems without duplication.
Instructions in Martini
- Use GraphQL mutations to create or update supported Linear objects.
- Store source identifiers and resulting Linear IDs for idempotency.
- Validate permissions and target references before mutation.
- Use bounded retries and backoff for transient errors while isolating validation and authorization failures.
Common Linear data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Issues | Track engineering, product, support, or incident work with status, priority, assignee, labels, estimates, and relationships. | GitHub, GitLab, Zendesk, Intercom, Sentry, Slack | Martini queries and mutates Issues through GraphQL, resolves team-specific workflow states, applies idempotency keys, and maps fields to canonical work-item models. |
| Projects | Organize Issues around larger initiatives and communicate project progress. | Notion, Slack, data warehouses, internal reporting APIs | Martini retrieves Projects and related summaries, transforms them into reporting or collaboration payloads, and can update supported fields through GraphQL. |
| Teams | Represent the organizational units that own Issues and define team-specific workflows. | Identity directories, reporting platforms, internal planning systems | Martini resolves Team identifiers and configuration before routing Issues, rather than relying on mutable display names. |
| Users | Represent workspace members who create, assign, and update Issues. | Identity systems, Slack, reporting platforms | Martini uses Users to resolve assignees and ownership mappings, subject to the permissions of the authenticated Linear user or OAuth application. |
| Cycles | Represent time-boxed planning periods associated with Teams and Issues. | Reporting platforms, planning tools, data warehouses | Martini retrieves Cycles through cursor-based queries, maps cycle dates and status to downstream planning models, and persists synchronization checkpoints. |
| Comments | Capture discussion and collaboration associated with Issues. | Slack, Zendesk, Intercom, knowledge platforms | Martini can synchronize selected Comments through GraphQL or webhook-driven workflows, applying source references and duplicate protection. |
Authentication and security considerations
Authentication and security
Linear supports bearer-token API keys for controlled internal integrations and OAuth 2.0 for applications acting on behalf of users or workspaces. OAuth scopes should be limited to the operations required, and access remains constrained by the authorizing user’s Linear permissions.
- Store API keys, OAuth client secrets, access tokens, and webhook signing secrets in secure Martini configuration.
- Validate Linear webhook signatures before accepting event data.
- Use separate credentials and configuration for development, test, and production environments.
- Protect exposed Martini APIs with appropriate authentication and authorization controls.
- Do not treat successful authentication as proof that the credential can access every Team, Project, Issue, or customer resource.
Operational considerations for Linear integrations
Operational considerations
Linear applies API usage limits and query-complexity controls. Requests should select only required fields, use bounded page sizes, avoid unbounded parallel mutations, and apply exponential backoff when transient failures occur.
- Persist cursors or checkpoints for collection synchronization and recover failed pages safely.
- Use event and resource identifiers for deduplication, and account for retries and out-of-order webhooks.
- Resolve Team-specific workflow states and workspace identifiers instead of relying on display names.
- Keep GraphQL documents version-controlled, monitor deprecated fields, and handle nullable fields and new enum values.
- Test mutations against a non-production workspace where possible and monitor workflow logs for authorization, rate, schema, and mapping errors.
- Handle file uploads as separate stages with bounded memory and explicit recovery for failed transfers or associations.
Why use Martini instead of scripts or point-to-point integrations?
Reliable orchestration beyond point-to-point scripts
Martini provides a maintainable integration layer between Linear and enterprise applications. Instead of embedding Linear calls in individual scripts, teams can centralize authentication, GraphQL requests, webhook handling, mappings, business rules, retries, and observability in reusable workflows and APIs.
- Combine Linear webhooks with scheduled cursor-based reconciliation.
- Expose normalized APIs so downstream systems do not need to understand Linear’s GraphQL model.
- Apply consistent idempotency, validation, routing, and error-handling policies across integrations.
- Separate environment configuration and secrets from integration logic.
- Extend workflows with custom logic when provider-specific transformations or correlation rules require it.
Frequently asked questions
Linear can be integrated primarily through its GraphQL API, which supports queries and mutations for Issues, Projects, Teams, Cycles, Comments, and related objects. Selected resources also support webhook notifications, while OAuth 2.0 and API keys provide authentication. Scheduled workflows with cursor-based pagination can support reconciliation and incremental synchronization.
Yes. Martini can consume Linear’s GraphQL API, receive selected Linear webhook events through a Martini API, validate webhook signatures, orchestrate workflows, map data, and call downstream systems. No native Martini Linear connector is documented in the supplied sources.
No. A dedicated Linear connector is not required. Martini can integrate with Linear using its GraphQL API, webhook events, OAuth 2.0, API keys, file-upload mechanisms, and other confirmed native integration endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Linear with Martini. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Linear, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Use the GraphQL API as the primary method for reading and modifying Linear data. Use webhooks for selected event-driven scenarios, OAuth 2.0 for applications acting on behalf of users or workspaces, API keys for controlled internal integrations, and cursor-based pagination for scheduled reconciliation. A separate REST or SOAP API should not be assumed.
Yes, Linear webhook requests can trigger a Martini API or webhook-facing workflow for selected resources and event types. The workflow should validate the signing secret, deduplicate events, inspect the action, and retrieve the current object through GraphQL when the webhook payload is incomplete. Webhooks do not necessarily cover every Linear change.
Martini can combine webhook processing with scheduled GraphQL queries and cursor-based pagination. It can persist cursors or checkpoints, maintain source-to-Linear identifier mappings, resolve team-specific workflow states, and retry transient failures. This hybrid approach supports both near-real-time updates and periodic reconciliation.
Yes. Martini can expose a controlled API that presents normalized enterprise endpoints while workflows translate requests into Linear GraphQL queries or mutations. The façade can centralize authentication, authorization, validation, field mapping, business rules, rate-aware processing, and error handling.
Related Martini documentation
Transformation
Connect Linear with your enterprise systems
Use Martini to build secure, observable Linear integrations around GraphQL, selected webhook events, scheduled synchronization, and reusable enterprise workflows.