Linear

Linear integration actions let workflows manage issues and related content through your installed Linear integration.

Prerequisites

• A Linear integration installed in your Port organization.
• Actions processing enabled for the integration.
• A Linear API key with access to the teams, issues, projects, and agents used by the workflow.

Configuration

All Linear integration actions share the same node structure:

Field	Type	Description
type	string	Required. Must be "INTEGRATION_ACTION".
installationId	string	Required. Your Linear integration identifier (for example linear) or installation ID. Set deferIntegrationInstallation to false when binding directly to the integration.
integrationProvider	string	Required. Must be "linear".
integrationInvocationType	enum	Required. One of the values listed in available actions.
integrationActionExecutionProperties	object	Required. Properties for the selected action.

Available actions

Each action is selected with the integrationInvocationType field:

Action	Invocation type	Description
Create an issue	create_issue	Create an issue in a Linear team
Create a sub-issue	create_sub_issue	Create a child of an existing issue
Update an issue	update_issue	Update an existing issue
Delegate to agent	delegate_issue_to_agent	Delegate an issue to a Linear agent
Archive an issue	archive_issue	Archive an issue
Delete an issue	delete_issue	Move an issue to Linear's trash
Add an issue comment	add_issue_comment	Add Markdown content to an issue
Add an issue reaction	add_reaction_to_issue	Add an emoji reaction to an issue
Add a document	add_document	Create a document associated with an issue or project

The remaining sections describe the execution properties of each action.

Issue actions

Manage an issue

Create, update, create sub-issues, delegate to agent, archive, or delete an issue.

Create

Creates an issue in a Linear team. Set integrationInvocationType to create_issue.

Execution properties

Field	Type	Description
teamId	string	Required. UUID of the Linear team.
title	string	Required. Issue title.
description	string	Issue description in Markdown.
assigneeId	string	UUID of the user assigned to the issue.
stateId	string	UUID of the workflow state assigned to the issue.
projectId	string	UUID of the associated project.
cycleId	string	UUID of the associated cycle.
priority	string	One of No priority, Urgent, High, Normal, or Low.
labelIds	array	UUIDs of labels attached to the issue.

Complete workflow example

Create issue with a self-service trigger (click to expand)

{
  "identifier": "linear_create_issue",
  "title": "Linear: Create issue",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "team": { "type": "string", "format": "entity", "blueprint": "linearTeam" },
            "title": { "type": "string" },
            "description": { "type": "string", "format": "markdown" },
            "priority": {
              "type": "string",
              "enum": ["No priority", "Urgent", "High", "Normal", "Low"],
              "default": "No priority"
            },
            "workflowState": {
              "type": "string",
              "format": "entity",
              "blueprint": "linearWorkflowState",
              "dependsOn": ["team"],
              "dataset": {
                "combinator": "and",
                "rules": [
                  {
                    "operator": "relatedTo",
                    "blueprint": "linearTeam",
                    "value": { "jqQuery": ".form.team.identifier" }
                  }
                ]
              }
            },
            "labels": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "entity",
                "blueprint": "linearLabel",
                "dataset": {
                  "combinator": "and",
                  "rules": [
                    {
                      "property": "isGroup",
                      "operator": "=",
                      "value": false
                    }
                  ]
                }
              }
            }
          },
          "required": ["team", "title"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "create_issue",
        "integrationActionExecutionProperties": {
          "teamId": "{{ .outputs.trigger.team | if type == \"object\" then .identifier else . end }}",
          "title": "{{ .outputs.trigger.title }}",
          "description": "{{ .outputs.trigger.description }}",
          "priority": "{{ .outputs.trigger.priority }}",
          "stateId": "{{ .outputs.trigger.workflowState | if type == \"object\" then .identifier else . end }}",
          "labelIds": "{{ .outputs.trigger.labels }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": ["{{ .result.issueUrl }}"]
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Create sub-issue

Creates a child of an existing issue. Set integrationInvocationType to create_sub_issue.

Execution properties

Field	Type	Description
parentId	string	Required. UUID or identifier of the parent issue, such as ENG-123.
title	string	Required. Sub-issue title.
teamId	string	Team UUID. The parent issue's team is used when omitted.
description	string	Issue description in Markdown.
assigneeId	string	UUID of the user assigned to the issue.
stateId	string	UUID of the workflow state assigned to the issue.
priority	string	One of No priority, Urgent, High, Normal, or Low.

Complete workflow example

Create sub-issue with a self-service trigger (click to expand)

{
  "identifier": "linear_create_sub_issue",
  "title": "Linear: Create sub-issue",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "parentIssue": { "type": "string", "format": "entity", "blueprint": "linearIssue" },
            "title": { "type": "string" },
            "description": { "type": "string", "format": "markdown" },
            "team": { "type": "string", "format": "entity", "blueprint": "linearTeam" },
            "priority": {
              "type": "string",
              "enum": ["No priority", "Urgent", "High", "Normal", "Low"],
              "default": "No priority"
            },
            "workflowState": {
              "type": "string",
              "format": "entity",
              "blueprint": "linearWorkflowState",
              "dependsOn": ["parentIssue", "team"],
              "dataset": {
                "combinator": "and",
                "rules": [
                  {
                    "operator": "relatedTo",
                    "blueprint": "linearTeam",
                    "value": {
                      "jqQuery": "if (.form.team | type) == \"object\" then .form.team.identifier else (.form.parentIssue.relations.team // \"\") end"
                    }
                  }
                ]
              }
            }
          },
          "required": ["parentIssue", "title"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "create_sub_issue",
        "integrationActionExecutionProperties": {
          "parentId": "{{ .outputs.trigger.parentIssue | if type == \"object\" then .identifier else . end }}",
          "title": "{{ .outputs.trigger.title }}",
          "description": "{{ .outputs.trigger.description }}",
          "teamId": "{{ .outputs.trigger.team | if type == \"object\" then .identifier else . end }}",
          "priority": "{{ .outputs.trigger.priority }}",
          "stateId": "{{ .outputs.trigger.workflowState | if type == \"object\" then .identifier else . end }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": ["{{ .result.issueUrl }}"]
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Update

Updates an existing issue. Set integrationInvocationType to update_issue. Provide at least one optional field to change.

Execution properties

Field	Type	Description
issueId	string	Required. UUID or identifier of the issue, such as ENG-123.
title	string	Updated issue title.
description	string	Updated issue description in Markdown.
assigneeId	string	UUID of the user assigned to the issue.
stateId	string	UUID of the workflow state.
projectId	string	UUID of the associated project.
cycleId	string	UUID of the associated cycle.
priority	string	One of No priority, Urgent, High, Normal, or Low.
labelIds	array	UUIDs of labels attached to the issue.

Complete workflow example

Update issue with a self-service trigger (click to expand)

{
  "identifier": "linear_update_issue",
  "title": "Linear: Update issue",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" },
            "title": { "type": "string" },
            "description": { "type": "string", "format": "markdown" },
            "workflowState": {
              "type": "string",
              "format": "entity",
              "blueprint": "linearWorkflowState",
              "dependsOn": ["issue"],
              "dataset": {
                "combinator": "and",
                "rules": [
                  {
                    "operator": "relatedTo",
                    "blueprint": "linearTeam",
                    "value": { "jqQuery": ".form.issue.relations.team" }
                  }
                ]
              }
            },
            "priority": {
              "type": "string",
              "enum": ["No priority", "Urgent", "High", "Normal", "Low"],
              "default": "No priority"
            },
            "labels": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "entity",
                "blueprint": "linearLabel",
                "dataset": {
                  "combinator": "and",
                  "rules": [
                    {
                      "property": "isGroup",
                      "operator": "=",
                      "value": false
                    }
                  ]
                }
              }
            }
          },
          "required": ["issue"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "update_issue",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}",
          "title": "{{ .outputs.trigger.title }}",
          "description": "{{ .outputs.trigger.description }}",
          "stateId": "{{ .outputs.trigger.workflowState | if type == \"object\" then .identifier else . end }}",
          "priority": "{{ .outputs.trigger.priority }}",
          "labelIds": "{{ .outputs.trigger.labels }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": ["{{ .result.issueUrl }}"]
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Delegate to agent

Delegates an issue to a Linear agent. Set integrationInvocationType to delegate_issue_to_agent. Delegation is separate from update_issue; use this dedicated action instead of setting a delegate on update.

Linear requires workspace AI settings with agent delegation enabled.

Execution properties

Field	Type	Description
issueId	string	Required. UUID or identifier of the issue.
delegateId	string	Required. UUID of the Linear agent.

Complete workflow example

Delegate issue to agent with a self-service trigger (click to expand)

{
  "identifier": "linear_delegate_issue",
  "title": "Linear: Delegate issue to agent",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" },
            "delegate": { "type": "string", "format": "entity", "blueprint": "linearUser" }
          },
          "required": ["issue", "delegate"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "delegate_issue_to_agent",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}",
          "delegateId": "{{ .outputs.trigger.delegate | if type == \"object\" then .identifier else . end }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": ["{{ .result.issueUrl }}"]
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Archive

Archives an issue. Set integrationInvocationType to archive_issue.

Execution properties

Field	Type	Description
issueId	string	Required. UUID or identifier of the issue.

Complete workflow example

Archive issue with a self-service trigger (click to expand)

{
  "identifier": "linear_archive_issue",
  "title": "Linear: Archive issue",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" }
          },
          "required": ["issue"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "archive_issue",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}"
        },
        "deferIntegrationInstallation": false
      }
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Delete

Moves an issue to Linear's trash. Set integrationInvocationType to delete_issue.

Execution properties

Field	Type	Description
issueId	string	Required. UUID or identifier of the issue.

Complete workflow example

Delete issue with a self-service trigger (click to expand)

{
  "identifier": "linear_delete_issue",
  "title": "Linear: Delete issue",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" }
          },
          "required": ["issue"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "delete_issue",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}"
        },
        "deferIntegrationInstallation": false
      }
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Changing issue status

Use update_issue with stateId to move an issue to another workflow state. Pick a linearWorkflowState entity filtered by the issue's team.

Add an issue comment

Adds Markdown content to an issue. Set integrationInvocationType to add_issue_comment.

Execution properties

Field	Type	Description
issueId	string	Required. UUID or identifier of the issue.
body	string	Required. Comment content in Markdown.

Complete workflow example

Add issue comment with a self-service trigger (click to expand)

{
  "identifier": "linear_add_issue_comment",
  "title": "Linear: Add issue comment",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" },
            "body": { "type": "string", "format": "markdown" }
          },
          "required": ["issue", "body"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "add_issue_comment",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}",
          "body": "{{ .outputs.trigger.body }}"
        },
        "deferIntegrationInstallation": false
      }
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Add an issue reaction

Adds an emoji reaction to an issue. Set integrationInvocationType to add_reaction_to_issue.

Execution properties

Field	Type	Description
issueId	string	Required. UUID or identifier of the issue.
emoji	string	Required. Emoji shortcode, such as +1, thumbsup, or eyes.

Complete workflow example

Add reaction to issue with a self-service trigger (click to expand)

{
  "identifier": "linear_add_reaction",
  "title": "Linear: Add reaction",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" },
            "emoji": { "type": "string", "description": "Emoji shortcode, such as eyes or thumbsup" }
          },
          "required": ["issue", "emoji"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "add_reaction_to_issue",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}",
          "emoji": "{{ .outputs.trigger.emoji }}"
        },
        "deferIntegrationInstallation": false
      }
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Document actions

Add a document

Creates a document associated with an issue or project. Set integrationInvocationType to add_document. Provide either issueId or projectId.

Execution properties

Field	Type	Description
title	string	Required. Document title.
content	string	Document content in Markdown.
issueId	string	UUID or identifier of the related issue.
projectId	string	UUID of the related project.

Complete workflow example

Add document with a self-service trigger (click to expand)

{
  "identifier": "linear_add_document",
  "title": "Linear: Add document",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "issue": { "type": "string", "format": "entity", "blueprint": "linearIssue" },
            "project": { "type": "string", "format": "entity", "blueprint": "linearProject" },
            "title": { "type": "string" },
            "content": { "type": "string", "format": "markdown" }
          },
          "required": ["title"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "add_document",
        "integrationActionExecutionProperties": {
          "title": "{{ .outputs.trigger.title }}",
          "content": "{{ .outputs.trigger.content }}",
          "issueId": "{{ .outputs.trigger.issue | if type == \"object\" then .identifier else . end }}",
          "projectId": "{{ .outputs.trigger.project | if type == \"object\" then .identifier else . end }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": ["{{ .result.documentUrl }}"]
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}

Action run outputs

Integration action nodes can expose outputs for downstream workflow steps (for example run links and follow-up automations).

Action	Output fields
create_issue, create_sub_issue, update_issue, delegate_issue_to_agent	identifier, issueId, issueUrl
archive_issue, delete_issue	issueId
add_issue_comment	commentId, issueId, body
add_reaction_to_issue	reactionId, issueId, emoji
add_document	documentId, documentUrl, title

Add a links array on the action node to surface URLs in the run UI, for example "{{ .result.issueUrl }}" or "{{ .result.documentUrl }}". Link expressions are evaluated when the action sets its output, typically when the run completes.

Build workflows using entity pickers

Most Linear execution properties, such as teamId or stateId, expect a raw UUID, which gives the person running the action no indication of what they're selecting (a workflow state UUID doesn't show that it resolves to "In Progress").

Define a SELF_SERVE_TRIGGER node with format: "entity" inputs so users select catalog entities by name or title instead, then use JQ in the action node to resolve the selected entity to the identifier its execution property expects. See the Complete workflow example under each action above for a full implementation of these entity-picker patterns.

Sync the relevant Linear blueprints first (linearTeam, linearIssue, linearWorkflowState, linearProject, linearCycle, linearLabel, linearUser).

Team identifiers

linearTeam entities may use a team key (for example GET) or a UUID as their identifier. Prefer passing the entity identifier from the picker rather than hard-coding team keys.

Entity input patterns

Catalog blueprint	Typical trigger field	Maps to action property
linearTeam	team	teamId
linearIssue	issue or parentIssue	issueId or parentId
linearWorkflowState	workflowState	stateId
linearProject	project	projectId
linearCycle	cycle	cycleId
linearLabel	labels (array)	labelIds
linearUser	assignee or delegate	assigneeId or delegateId

Use this JQ helper when a trigger field can be either an entity object or a plain identifier:

{{ .outputs.trigger.team | if type == "object" then .identifier else . end }}

Filter workflow states by team

linearWorkflowState entities are related to a linearTeam. Filter the picker with dependsOn and a relatedTo dataset rule:

{
  "workflowState": {
    "title": "Workflow State",
    "type": "string",
    "format": "entity",
    "blueprint": "linearWorkflowState",
    "dependsOn": ["team"],
    "dataset": {
      "combinator": "and",
      "rules": [
        {
          "operator": "relatedTo",
          "blueprint": "linearTeam",
          "value": { "jqQuery": ".form.team.identifier" }
        }
      ]
    }
  }
}

For update issue, filter by the selected issue's team:

"value": { "jqQuery": ".form.issue.relations.team" }

For create sub-issue, use the override team or inherit from the parent issue:

"value": {
  "jqQuery": "if (.form.team | type) == \"object\" then .form.team.identifier else (.form.parentIssue.relations.team // \"\") end"
}

Exclude label groups from the picker

linearLabel entities include both labels and label groups. Linear only accepts child label IDs in labelIds, not group IDs. Filter the picker with isGroup = false:

{
  "labels": {
    "title": "Labels",
    "type": "array",
    "items": {
      "type": "string",
      "format": "entity",
      "blueprint": "linearLabel",
      "dataset": {
        "combinator": "and",
        "rules": [
          {
            "property": "isGroup",
            "operator": "=",
            "value": false
          }
        ]
      }
    }
  }
}