Linear

Loading version...

Port's Linear integration allows you to model Linear resources in your software catalog and ingest data into them.

Supported resources TeamIssueLabel

Core support

Live eventsSee supported resources

Setup

Choose one of the following installation methods. Not sure which method is right for your use case? Check the available installation methods.

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Default mapping configuration

This is the default mapping configuration you get after installing the Linear integration.

Default mapping configuration (Click to expand)

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: team
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .key
        title: .name
        blueprint: '"linearTeam"'
        properties:
          description: .description
          workspaceName: .organization.name
          url: '"https://linear.app/" + .organization.urlKey + "/team/" + .key'
- kind: label
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .name
        blueprint: '"linearLabel"'
        properties:
          isGroup: .isGroup
        relations:
          parentLabel: .parent.id
          childLabels: '[.children.edges[].node.id]'
- kind: issue
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .identifier
        title: .title
        blueprint: '"linearIssue"'
        properties:
          url: .url
          status: .state.name
          assignee: .assignee.email
          creator: .creator.email
          priority: .priorityLabel
          created: .createdAt
          updated: .updatedAt
        relations:
          team: .team.key
          labels: .labelIds
          parentIssue: .parent.identifier
          childIssues: .children.edges[].node.identifier

Monitoring and sync status

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Mapping & selectors per resource

To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your data sources page. Find the integration in the list of data sources and click on it to open the playground.

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: team
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"linearTeam"'
          properties:
            description: .description
            workspaceName: .organization.name
            url: '"https://linear.app/" + .organization.urlKey + "/team/" + .key'

{
  "id": "92d25fa4-fb1c-449f-b314-47f82e8f280d",
  "name": "Port",
  "key": "POR",
  "description": null,
  "organization": {
      "id": "36968e1b-496c-4610-8c25-641364da172e",
      "name": "Getport",
      "urlKey": "getport"
  }
}

{
  "identifier": "POR",
  "title": "Port",
  "icon": "Linear",
  "blueprint": "linearTeam",
  "team": [],
  "properties": {
      "url": "https://linear.app/getport/team/POR",
      "workspaceName": "Getport"
  },
  "relations": {},
  "createdAt": "2024-05-19T16:19:15.232Z",
  "createdBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE",
  "updatedAt": "2024-05-19T16:19:15.232Z",
  "updatedBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE"
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: label
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"linearLabel"'
          properties:
            isGroup: .isGroup
          relations:
            parentLabel: .parent.id
            childLabels: "[.children.edges[].node.id]"

{
  "id": "36f84d2c-7b7d-4a71-96f2-6ea4140004d5",
  "createdAt": "2024-05-17T15:17:40.858Z",
  "updatedAt": "2024-05-17T15:17:40.858Z",
  "archivedAt": null,
  "name": "New-sample-label",
  "description": null,
  "color": "#bec2c8",
  "isGroup": true,
  "parent": null,
  "children": {
      "edges": [
          {
              "node": {
                  "id": "2e483c90-2aca-4db6-924d-b0571d49f691"
              }
          }
      ]
  }
}

{
  "identifier": "36f84d2c-7b7d-4a71-96f2-6ea4140004d5",
  "title": "New-sample-label",
  "icon": "Linear",
  "blueprint": "linearLabel",
  "team": [],
  "properties": {
      "isGroup": false
  },
  "relations": {
      "childLabels": [],
      "parentLabel": null
  },
  "createdAt": "2024-05-19T16:19:17.747Z",
  "createdBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE",
  "updatedAt": "2024-05-19T16:19:17.747Z",
  "updatedBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE"
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: issue
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .identifier
          title: .title
          blueprint: '"linearIssue"'
          properties:
            url: .url
            status: .state.name
            assignee: .assignee.email
            creator: .creator.email
            priority: .priorityLabel
            created: .createdAt
            updated: .updatedAt
          relations:
            team: .team.key
            labels: .labelIds
            parentIssue: .parent.identifier
            childIssues: .children.edges[].node.identifier

{
  "id": "9b4745c2-a8e6-4432-9e56-0fa97b79ccbf",
  "createdAt": "2024-05-16T21:52:00.299Z",
  "updatedAt": "2024-05-17T09:27:40.077Z",
  "archivedAt": null,
  "number": 2,
  "title": "sub issue with new title",
  "priority": 3,
  "estimate": null,
  "sortOrder": -991,
  "startedAt": null,
  "completedAt": null,
  "startedTriageAt": null,
  "triagedAt": null,
  "canceledAt": null,
  "autoClosedAt": null,
  "autoArchivedAt": null,
  "dueDate": null,
  "slaStartedAt": null,
  "slaBreachesAt": null,
  "trashed": null,
  "snoozedUntilAt": null,
  "labelIds": [
      "402b218c-938c-4ddf-85db-0019bc632316"
  ],
  "previousIdentifiers": [],
  "subIssueSortOrder": -56.17340471045278,
  "priorityLabel": "Medium",
  "integrationSourceType": null,
  "identifier": "POR-2",
  "url": "https://linear.app/getport/issue/POR-2/sub-issue-with-new-title",
  "branchName": "mor/por-2-sub-issue-with-new-title",
  "customerTicketCount": 0,
  "description": "",
  "descriptionState": "AQG/pOWPAgAHAQtwcm9zZW1pcnJvcgMJcGFyYWdyYXBoAA==",
  "team": {
      "id": "92d25fa4-fb1c-449f-b314-47f82e8f280d",
      "name": "Port",
      "key": "POR"
  },
  "state": {
      "name": "Todo"
  },
  "creator": {
      "name": "Mor Paz",
      "email": "mor@getport.io"
  },
  "assignee": {
      "name": "Dudi Elhadad",
      "email": "dudi@getport.io"
  },
  "parent": {
      "id": "5ddd8e85-ad89-4c96-b901-0b901b29100d",
      "identifier": "POR-1"
  }
}

{
  "identifier": "POR-2",
  "title": "sub issue with new title",
  "icon": "Linear",
  "blueprint": "linearIssue",
  "team": [],
  "properties": {
      "status": "Todo",
      "url": "https://linear.app/getport/issue/POR-2/sub-issue-with-new-title",
      "created": "2024-05-16T21:52:00.299Z",
      "priority": "Medium",
      "assignee": "dudi@getport.io",
      "updated": "2024-05-17T09:27:40.077Z",
      "creator": "mor@getport.io"
  },
  "relations": {
      "team": "POR",
      "labels": [
          "402b218c-938c-4ddf-85db-0019bc632316"
      ],
      "parentIssue": "POR-1"
  },
  "createdAt": "2024-05-19T16:19:21.143Z",
  "createdBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE",
  "updatedAt": "2024-05-19T16:19:21.143Z",
  "updatedBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE"
}

Set up live events

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Hosted by Port

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

Self-hosted

BaseUrl & webhook configuration

To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Linear integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.

• If Linear and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
  For Kubernetes deployments, create a service to expose the integration pod and use the service URL as liveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient.
• If Linear is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Linear can reach.

If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.

Debugging local integrations

To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)