A Google Apps Script tool for creating and updating bulk issues in Linear directly from a Google Sheet.
This tool lets you prepare issues in a spreadsheet and upload them to one or more Linear teams in a single operation. It supports creating new issues, updating existing ones, and setting relations between issues. It is based on the Jira Google Sheets Uploader and follows the same sheet structure and workflow.
- In Linear, go to Settings → Account → Security & Access → API Keys
- Create a new personal API key and copy it
- Store it somewhere safe (e.g. a password manager) — you will be prompted for it when running the script
Make a copy of the template Google Sheet. All configuration and data entry happens within the sheet.
Open the Config tab and fill in the following:
Defaults — used when a row does not specify a value:
- Default Issue Priority
- Default Issue Type
Priority Table — maps your label names to Linear's numeric priority values:
| Label | Linear Value |
|---|---|
| Urgent | 1 |
| High | 2 |
| Medium | 3 |
| Low | 4 |
| No Priority | 0 |
You can rename the labels to anything (e.g. P0/P1/P2), as long as the corresponding Linear value (0–4) is set in the cfgPriorityValue column. If left empty, the defaults above are used as a fallback.
Issue Link Table — maps your label names to Linear relation types (blocks, duplicate, related):
| Label | Linear Type |
|---|---|
| Blocks | blocks |
| Is blocked by | blocks |
| Duplicates | duplicate |
| Related to | related |
Labels are case-insensitive. If left empty, common label names are matched automatically as a fallback.
On the main sheet, go to ⚙️ Linear Uploader → Sync Teams and Members. This downloads:
- All Linear teams you have access to (key + name), saved to the Projects and Users tab
- All active organisation members (name + ID), also saved to the Projects and Users tab
You will be prompted for your API key on first use. If Ask for API Key is unchecked in the Config tab, the key is remembered for your browser session via Google's UserProperties service — it is never written to the sheet.
- Fill in your issue data on the main sheet. Project and Summary are required for all rows. All other fields are optional and will use configured defaults where applicable.
- Go to ⚙️ Linear Uploader → Send Data to Linear
- Issues are created one by one. The Status column updates in real time. On success, the Key column is populated with a clickable link to the issue in Linear, and the Skip checkbox is automatically checked.
Rows with Skip checked and a value in the Key column will be updated rather than recreated. The following fields are updated: Summary, Description, Assignee, Parent, and Priority.
To link two issues, set the IssueLink column to the row number of the issue you want to link to, and set IssueLinkType to one of your configured link labels (e.g. "Blocks"). Relations are processed in a second pass after all issues have been created, so both issues must exist (either created in this run or already present with a Key value).
Some fields are hidden by default. To show them, go to ⚙️ Linear Uploader → Show Advanced Columns.
To clear all issue data and start fresh, go to ⚙️ Linear Uploader → Reset Sheet (Clear Issues).
| Field | Description | Required | Updated on Rerun |
|---|---|---|---|
| Project | Linear team key (e.g. ENG) |
Yes | No |
| Summary | Issue title | Yes | Yes |
| Description | Issue body | No | Yes (cleared if blank) |
| Assignee | Member ID (from Projects and Users tab) | No | Yes (unassigned if blank) |
| Priority | Priority label (from Config tab) | No, default used | Yes |
| IssueLinkType | Relation label (from Config tab) | No | Yes |
| IssueLink | Row number of the issue to relate to | No | Yes |
| Jira | Linear | |
|---|---|---|
| API style | REST | GraphQL |
| Auth | Username + API token (Base64) | Single API key |
| Project identifier | Project key (e.g. ABC) |
Team key (e.g. ENG) |
| Priority | Custom strings per instance | Fixed numeric values (0–4) |
| Issue linking | Named inward/outward types | blocks, duplicate, related |
| Subdomain config | Required | Not needed |
"Could not resolve team key" — The value in the Project column doesn't match any team key. Run Sync Teams and Members and check the Projects and Users tab for the correct keys.
"issueCreate returned success: false" — The API accepted the request but Linear rejected it, usually due to a missing required field for that team's configuration. Check the Apps Script logs (Extensions → Apps Script → Executions) for the full error.
"Cannot add relation: linked issue has no ID" — The issue referenced in the IssueLink column failed to create earlier in the run. Fix the error on that row first and rerun.
API key not being remembered — Make sure Ask for API Key is unchecked in the Config tab. The key is stored per Google account using UserProperties, so it persists across sessions for the same user.