Linear Integration

Connect ElasticClaw to Linear to sync agent tasks with your team's issues and projects.

How it works

ElasticClaw watches Linear issue update webhooks for workflows with atrigger.linear source. When an issue enters a matching state, ElasticClaw Server creates an agent, injects issue context, and passes the Linear token as LINEAR_API_KEY.

  • Read the issue title, description, comments, state, team, labels, and assignee
  • Require labels and suppress automation with exclude_labels
  • Move issues through workflow stages configured by the workflow
  • Post comments when a workflow agent is stopped because the issue left the trigger status
  • Expose a small claw-bridge linear CLI inside the sandbox for issue get, update, search, and teams

Configure Linear

1. Create a Linear API Token

  1. Go to Linear → Settings → API → Personal API Keys
  2. Click Create key, give it a name like "ElasticClaw"
  3. Copy the token — you won't see it again
bash
export LINEAR_API_TOKEN=lin_api_xxxxxxxxxxxxx

2. Configure the workspace issue tracker

text
Settings -> Workspaces -> my-app -> Issue Trackers
Add Linear:
  workspace: my-company
  token: ${LINEAR_API_TOKEN}
  webhook secret: ${LINEAR_WEBHOOK_SECRET}
Issue tracker credentials and webhook secrets are stored with the workspace.

3. Configure Linear webhook

Point a Linear webhook at ElasticClaw Server. ElasticClaw handles only LinearIssue update events.

  • Payload URL: https://server.example.com/api/workspaces/my-app/webhooks/linear
  • Secret: the Linear webhook secret configured for the workspace issue tracker

Workflow configuration

Linear workflows use trigger.linear. If the ElasticClaw workspace has one Linear connection, the workflow uses it automatically. The optional team field is the Linear team key from issue identifiers, such as ENG in ENG-123; it is not a Linear team ID.

yaml
# .elasticclaw/workflows/bugfix.yaml
schema_version: v1
name: bugfix
trigger:
  linear:
    event: status_changed
    team: ENG
    states:
      - "Ready for Agent"
    labels:
      - bug
    exclude_labels:
      - blocked

stages:
  - id: working
    label: Working
    entry: true
    on_enter:
      move_issue: "In Progress"
      inject: |
        Issue: {{.Issue.Identifier}} - {{.Issue.Title}}
        URL: {{.Issue.URL}}

        Read CONTEXT.md and start working.

  - id: pr_opened
    label: PR Opened
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      move_issue: "In Review"

  - id: merged
    label: Merged
    triggers:
      - pr_merged: {}
    on_enter:
      move_issue: Done
    terminal: true

Workspace integration

Push the workspace and workflow separately:

bash
elasticclaw workspace push my-app
elasticclaw workflow push --workspace my-app .elasticclaw/workflows/bugfix.yaml

The workflow uses the Linear connection configured for the ElasticClaw workspace. Workflow filtering uses trigger.linear.team.

Label filters

Linear triggers require every configured labels value and reject issues that have any configured exclude_labels value. Use this to keep automation away from issues that are blocked, on hold, or explicitly reserved for humans.

yaml
trigger:
  linear:
    team: ENG
    states: ["Ready for Agent"]
    labels: [bug]
    exclude_labels: [blocked, needs-human-review]

Template variables

In stages[].on_enter.inject, automatic Linear workflows expose this complete issue object:

{{.Issue.Identifier}} — Linear issue key, such as ENG-123.

{{.Issue.Title}} — Linear issue title.

{{.Issue.URL}} — Browser URL for the issue.

{{.Issue.Description}} — Linear issue description.

Linear API tokens have full read/write access to your workspace. Use a dedicated service account for production deployments.