Linear

Back up your Linear workspace to your own cloud storage.

Linear is a project and issue tracking tool for software teams. SimpleBackups connects to Linear with a read-only OAuth connection, exports your workspace content through the Linear API on a schedule, and stores it as a compressed archive on the storage provider of your choice. This guide covers how to connect your workspace, configure a backup, and access your backed-up data.

Create a Linear backup

Connect your Linear workspace

1. In SimpleBackups, create a new backup and choose Linear.
2. Click Connect Linear workspace. You are redirected to Linear to authorize SimpleBackups.
3. Review the request and click Authorize. SimpleBackups requests read-only access, and content is accessed by the integration itself rather than through your personal user account.

Once authorized, you are redirected back to SimpleBackups and the new connection is selected automatically. Your OAuth tokens are encrypted at rest, and SimpleBackups refreshes them automatically before each run.

Configure your backup

1. Select the Account connection to back up. Each connection maps to one Linear workspace.
2. Choose a Backup mode:
   • Resilient (recommended) — the run stops and is marked failed if any core content (issues, comments, projects, teams) cannot be captured, so an incomplete backup is never reported as a success. Everything captured up to that point is kept, and the run's Content tab still shows the partial counts and what failed. Optional content that fails is recorded and retried on the next run.
   • Simple — a single pass that keeps going after content failures and reports success, with the failures recorded in the run's Content tab instead of failing the run. (A fully exhausted Linear API rate limit still stops either mode.) Choose this only if you prefer an incomplete backup over a failed one.
3. Name your backup, then choose your schedule and storage destination.

Run and verify your backup

After creating the backup, you can run it on demand with Run Now. Each run reports per-entity counts — how many issues, comments, projects, and other records were captured — in the log's Content tab, and the backup page shows these counts across runs. Anything that could not be captured is listed per run, so a degraded backup is always visible. Runs that fail partway still appear with the counts they captured and a warning that they are not a reliable restore point.

One connection per workspace

Each Linear workspace can be connected to SimpleBackups once. Linear issues a single backup authorization per workspace, so authorizing again supersedes the existing connection's access rather than adding to it.

iReconnecting an already-connected workspace

If you authorize a workspace that is already connected, SimpleBackups refreshes the existing connection with your new authorization — its scheduled backups keep working — and does not create a duplicate. If the workspace is connected under a different account, disconnect it there before reconnecting here.

What a backup contains

SimpleBackups backs up every team your workspace has granted to the SimpleBackups app, along with workspace-level content, including archived items. Each entity type is exported as a standard JSON Lines (.jsonl) file, and all files are packaged into a compressed archive (optionally encrypted) on your storage.

A backup captures:

• Issues — including sub-issues, archived issues, estimates, priorities, assignees, and issue relations (blocking, duplicates)
• Comments — full comment threads on issues, project updates, initiatives, and documents
• Projects — including milestones, project updates, labels, members, and external links
• Cycles and workflow states — with each team's cycle settings
• Teams, members, and users — including external users
• Labels — with label groups and hierarchy
• Documents — full document content
• Initiatives — including initiative updates and linked projects
• Attachments — title, URL, and metadata for linked resources
• Templates, custom views, and project statuses

Records keep their identifiers and cross-references, so relationships between issues, projects, teams, and users are preserved in the exported data.

Restore a Linear backup

You restore a Linear backup by downloading the archive and working with the exported data directly. In-app restore into a Linear workspace is not available yet.

1. Navigate to the backup summary page and find the point-in-time log you want. Click the info button to open the log summary.
2. Generate a signed download link or use the Backup Archive link, and download the archive.
3. Extract the archive. It contains one .jsonl file per entity type, with one JSON record per line.

iNote

JSON Lines is a plain-text format readable by any programming language and most data tools. You can inspect records directly, load them into a database or spreadsheet, or convert issues to CSV for Linear's built-in importer.

Requirements

SaaS app backups run on SimpleBackups' serverless infrastructure by default, which already includes everything needed. If you instead run this backup on your own connected server, that server must have Python 3 and pip installed — the recipe uses them to call the Linear API.

Limitations

Linear backups have the following limitations:

• Team access is controlled in Linear — the backup covers the teams your workspace has granted the SimpleBackups app access to. Workspace admins manage this from the app's settings in Linear; a team the app cannot see is not included in the backup.
• Whole accessible workspace only — a backup covers every team the app can access; per-team selection in SimpleBackups is not available yet.
• Attachment files are referenced, not downloaded — attachments are captured as their title, URL, and metadata. The underlying uploaded file bytes are not included in the archive.
• Issue history is not captured — the per-issue activity feed (state changes, reassignments) is not exported; the current state of every issue is.
• No in-app restore — restoring means downloading the archive and re-importing data yourself (see Restore a Linear backup above).

iRate limits are handled for you

Linear applies API rate limits per connection. SimpleBackups paces its requests and waits out rate-limit windows automatically, so large workspaces back up reliably — a run on a very large workspace simply takes longer.