Skip to main content

CREATE A LINEAR EPIC WITH CHILD SUB-ISSUES

This guide shows you how to create a parent Linear issue and its child sub-issues in one run of the createEpic method of @mgreten/linear.

Prerequisites

  • A Linear personal API key stored in a vault named linear under the key api-key (see Vaults)
  • The ID of the Linear team the epic belongs to, shown below as TEAM_ID

Pull the extension

swamp extension pull @mgreten/linear

You will see output like:

INF extension·pull: Pulling "@hivemq/linear"@"2026.03.30.14"
INF extension·pull: Identity verified: "@hivemq/linear"@"2026.03.30.14"
INF extension·pull: Pulled "@hivemq/linear"@"2026.03.30.14"
INF extension·pull: Extracted 6 files:

Set up the behavior

Create a behavior named linear-planning of type @mgreten/linear (see Create and Run a Behavior). Set its apiKey global argument to a vault expression and defaultTeamId to the epic's team:

globalArguments:
  apiKey: "${{ vault.get('linear', 'api-key') }}"
  defaultTeamId: "TEAM_ID"

Choose a starting state

If the parent issue should start in a state other than the team's default, list the team's workflow states:

swamp behavior run linear-planning listStates --input teamId=TEAM_ID

This command fetches the team's workflow states from Linear and records each one as a workflowState resource. Copy the ID of the state you want and add "stateId":"STATE_ID" to the parent object in the next step. Children accept stateId as well.

Create the epic

Pass the parent as a JSON object and the children as a JSON array:

swamp behavior run linear-planning createEpic \
  --input 'parent:json={"title":"Checkout redesign","description":"Replace the legacy checkout flow","teamId":"TEAM_ID","priority":2}' \
  --input 'children:json=[{"title":"Design the new cart page","estimate":2},{"title":"Implement the payment form","estimate":3},{"title":"Migrate saved addresses","estimate":1}]'

This command creates the parent issue, then creates each child as a sub-issue linked to it, and records the issues as issue resources.

Adjust the inputs to fit the epic:

  • Each child without a teamId goes into the parent's team. To file a child in another team, give it its own teamId.
  • The parent and each child accept title, description, teamId, projectId, priority, stateId, assigneeId and estimate. Only title is required.
  • To put the whole epic in a project, set projectId on the parent and on each child.

Check the parent issue

Fetch the parent by its identifier, replacing ENG-123 with the identifier Linear gave it:

swamp behavior run linear-planning getIssue --input identifier=ENG-123

This command fetches the issue from Linear and records it as an issue resource with its relations resolved, including the sub-issues created in the previous step.

Refer to the Linear extensions reference for every method and input of @mgreten/linear.