Export a generated brief to Linear when you want it in your team's work queue. Each export creates an issue and stores its identity in ShipFoundry. Matching an update does not create an issue automatically.

Connect and choose a target

Connect Linear in Integrations and approve the workspace.
Under Project Targets, choose Project Delivery for the ShipFoundry project. You can also open Delivery from the project's navigation.
Select a team and, optionally, a Linear project, starting status, labels, assignee and priority. Choose Save Linear Target.

Each ShipFoundry project has its own target. For example, one product can send issues to its Linear project with a product:a label while another uses a different team, project and labels. Owners and admins can edit targets; members can inspect them.

Projects, statuses and labels follow the selected team. Changing teams clears incompatible selections. Choose Labels searches existing labels, including product or source tags such as from-shipfoundry. Real Linear label groups allow one choice per group; ordinary labels can be combined. Create new labels in Linear, then reload Project Delivery.

Saving this target uses the standard issue format for briefs without a type-specific template. Type-specific templates keep their destinations and labels. Manage This Project's Templates opens the matching project's library if you need different routing for research, spikes or other brief types.

The connection uses OAuth. ShipFoundry stores its access token encrypted on the server; your coding agent does not need that token.

Export a brief

Open a generated brief and review its evidence and task instructions. Choose Create Linear issue, then check the returned issue link.

An agent can check the connection and preview an issue before exporting through MCP or the API. Export requires explicit confirmation. Keep the same idempotency key on retries and reuse the stored issue link when the brief was already exported.

Research, engineering, workflow, strategy and implementation briefs can become issues. An update with No Packet needs its missing context or evidence resolved first.

Customize the issue format

See the complete template reference for all 39 fields, built-in formats, destinations, lifecycle controls and API/MCP/CLI request examples.

Open Connected Apps → Manage Linear Templates, then choose your ShipFoundry project.

Start with the built-in format for your brief type. Choose Create From Default to make a named custom template.
Edit the title and Markdown body. Browse Variables shows common fields; search or choose Show Advanced Fields for execution details. {{brief}} inserts the complete handoff, so use either that or the individual sections to avoid duplication.
Choose a Linear team, optional project, starting status and labels. Choose Labels opens a searchable picker. Real Linear groups allow one choice per group. A colon in an ordinary label name does not impose this restriction. Leave status blank to use the team's default.
Render a preview with an existing brief, then save the template. Replace Draft With Built-In changes the draft only.
Choose Use For This Brief Type or Use As Fallback to apply the saved version to future exports.

Each named template has one library entry. Version History lives inside Edit Template. To revert, load an earlier version, choose Save Restored Version, then select it as the default if needed. Saving does not change the active default or rewrite an existing Linear issue.

Archive removes a custom template from use without losing history. Open Archived Templates to restore it. An archived default uses the built-in format with its saved destination; restoring re-enables the pinned version. Use Built-In resets one brief type while preserving its destination and other type defaults. Owners and admins can manage templates; members with read access can inspect them.

Templates can apply to any brief type or a specific type: implementation handoff, configuration packet, engineering spike, research, workflow or strategy. A type mismatch is rejected before export. Templates format the brief; they do not make a recommendation executable or bypass its readiness checks.

Variables are literal substitutions. Unknown variables, helpers and nested expressions are rejected. Braces inside brief content stay literal. A brief without an executable packet says so when you use {{taskPacket}}.

Use templates from an agent

Use shipfoundry.linear_template_options to read destinations and shipfoundry.list_linear_templates to read versions and variable names. Both take projectId.

shipfoundry.save_linear_template saves a version with confirmed: true. For a new template, omit templateId and use expectedVersion: 0. For an existing template, send its templateId and latest version number. A concurrent edit returns template_conflict; reload before saving again. shipfoundry.select_linear_template takes projectId, revisionId and confirmed: true to select a default.

Preview and export accept an optional templateRevisionId. Omitting it uses the project's default, or the original handoff format when no default is selected. Keep the same idempotency key when retrying a write.

Use shipfoundry.manage_linear_template with confirmed: true to archive or restore a custom template (action, projectId, templateId, expectedVersion), or reset a type to built-in (action: "reset_default", projectId, outputKind, destination). Use outputKind: null to reset the fallback. Archive and restore require the latest version number; reload after a conflict.

The API exposes the same operations at /api/v1/linear/templates, /api/v1/linear/templates/options, /api/v1/linear/templates/select and /api/v1/linear/templates/manage. CLI equivalents:

shipfoundry linear template-options --project PROJECT_ID --json
shipfoundry linear templates --project PROJECT_ID --json
shipfoundry linear preview-template --file draft.json --json
shipfoundry linear save-template --file template.json --yes
shipfoundry linear select-template --project PROJECT_ID --template REVISION_ID --yes
shipfoundry linear manage-template --file management.json --yes
shipfoundry linear preview --match UPDATE_ID --template REVISION_ID --json
shipfoundry linear export --match UPDATE_ID --template REVISION_ID --yes

A template file contains:

{
  "projectId": "SHIPFOUNDRY_PROJECT_UUID",
  "expectedVersion": 0,
  "name": "Factory Handoff",
  "titleTemplate": "{{title}}",
  "bodyTemplate": "## Task\n{{context}}\n\n## Steps\n{{suggestedSteps}}\n\n## Return\n{{acceptanceCriteria}}\n\n{{taskPacket}}\n\n{{briefUrl}}",
  "outputKind": null,
  "destination": {
    "teamId": "LINEAR_TEAM_UUID",
    "projectId": null,
    "stateId": null,
    "labelIds": []
  }
}

Replace the identifiers with values returned by the tools. A template's destination must belong to its selected Linear team.

Record the result in ShipFoundry

Linear issue status does not sync back to ShipFoundry. When the work finishes, have your agent or automation record the outcome against the original update, with implementation or investigation evidence.

This integration exports briefs; it does not import issues or synchronize the rest of your Linear workspace. You can use ShipFoundry without connecting Linear.

If export fails

Check that the Linear connection is active and the project has an enabled export target. If the target is wrong, correct it before exporting another brief. If an issue was already created, use its stored link rather than creating a duplicate.

See agent workflows for other ways to pass tasks to your tools.

Brief Types And Variables

Each brief type can have its own template and Linear destination. Choose Create From Default, edit the Markdown, save, then select Use For This Brief Type. A template for Any Brief Type can be the fallback. An explicitly selected export template takes priority over these defaults. Saved versions remain unchanged when you edit another draft.

Browse Variables opens the searchable field guide. It explains every placeholder, marks variables used in your draft, and identifies fields that require an execution packet. Insert at your cursor in the title or body. {{sourceUrl}} is the original update; {{briefUrl}} opens the ShipFoundry recommendation. {{brief}} inserts the full default handoff, so avoid adding the same sections again unless you want duplication.

Replace Draft With Built-In restores the draft for the selected brief type. Preview uses a real brief and lists inserted variables that have no value. Optional execution fields remain empty when that brief has no execution packet. Preview does not create an issue.

Agents receive the same variable guide, built-in presets and per-type defaults from shipfoundry.list_linear_templates, GET /api/v1/linear/templates, or shipfoundry linear templates --project <project-id> --json.

Linear