---
title: "Linear Connector"
description: "Vollständiger Leitfaden zur Linear-Integration für die Synchronisierung von Issues, Projekten und Team-Aktivitätsdaten mit Brevo über Tajo."
url: https://tajo.io/de/docs/connectors/custom/linear/
markdown: https://tajo.io/de/docs/connectors/custom/linear.md
lang: de-DE
robots: noindex
---

Beantrage frühzeitigen Zugang

Gib deinen Vornamen und deine geschäftliche E-Mail-Adresse ein. Wir senden dir einen Link, mit dem du deine Anfrage für den Tajo-Zugang bestätigst.

# Linear Connector

Connector-Status: Geplant Noch nicht gebaut. Tajo betreibt diesen Connector heute nicht.

| Quellfeld | Zielfeld | Beispielwert |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Verbinde deinen Linear-Workspace über Tajo mit Brevo für kundenorientiertes Issue-Tracking, Produkt-Update-Benachrichtigungen und Entwicklungs-Meilenstein-Kampagnen.

## Überblick

| Eigenschaft | Wert |
| --- | --- |
| **Plattform** | Linear |
| **Kategorie** | Custom |
| **Einrichtungsaufwand** | Einfach |
| **Offizielle Integration** | Nein |
| **Synchronisierte Daten** | Issues, Projekte, Nutzer:innen, Events |
| **API-Typ** | GraphQL API |
| **Authentifizierung** | OAuth 2.0 / Persönlicher API-Key |
| **Basis-URL** | `https://api.linear.app/graphql` |

## Funktionen

- **Issue-Event-Synchronisierung** - Leite Issue-Erstell-, Update- und Abschluss-Events in Brevo-Kontaktverläufe weiter
- **Projekt-Meilenstein-Tracking** - Löse Brevo-Kampagnen aus, wenn Projekte wichtige Meilensteine erreichen
- **Kundenbezogene Issue-Verknüpfung** - Verknüpfe Linear-Issues mit Brevo-Kontakten für Support-Sichtbarkeit
- **Label-basierte Segmentierung** - Ordne Linear-Labels Brevo-Kontaktattributen zu
- **Cycle-Analytics** - Synchronisiere Sprint-/Cycle-Abschlussdaten für das Team-Performance-Reporting
- **Webhook-gesteuerte Automatisierung** - Echtzeit-Event-Weiterleitung über Linear-Webhooks

## Voraussetzungen

Bevor du beginnst, stelle sicher, dass du Folgendes hast:

1. Einen Linear-Workspace mit Admin-Zugriff
2. Einen persönlichen API-Key oder eine konfigurierte OAuth-Anwendung
3. Ein Brevo-Konto mit API-Zugriff
4. Ein Tajo-Konto mit aktivem Abonnement

## Authentifizierung

Linear unterstützt persönliche API-Keys und OAuth 2.0.

### Option 1: Persönlicher API-Key

1. Gehe in **Linear** zu **Settings** > **API** > **Personal API keys**
2. Klicke auf **Create key**
3. Benenne ihn mit “Tajo Integration”
4. Kopiere den generierten Key (beginnt mit `lin_api_`)

```bash
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}'
```

### Option 2: OAuth 2.0

Für Integrationen, die mehrere Workspaces bedienen:

1. Erstelle eine OAuth-Anwendung unter [linear.app/settings/api/applications](https://linear.app/settings/api/applications)
2. Konfiguriere die Redirect-URI: `https://app.tajo.io/callbacks/linear`
3. Fordere die Scopes an: `read`, `write`, `issues:create`, `comments:create`

GraphQL API

Linear verwendet ausschließlich eine GraphQL-API. Alle Queries und Mutations laufen über einen einzigen Endpunkt: `https://api.linear.app/graphql`. Tajo übernimmt die Erstellung aller GraphQL-Abfragen automatisch.

### Verbindung zu Tajo herstellen

```bash
# Using Personal API Key
tajo connectors install linear \
  --api-key $LINEAR_API_KEY

# Using OAuth
tajo connectors install linear \
  --client-id $LINEAR_CLIENT_ID \
  --client-secret $LINEAR_CLIENT_SECRET
```

## Konfiguration

### Grundeinrichtung

```yaml
connectors:
  linear:
    enabled: true

    sync:
      issues: true
      projects: true
      cycles: true
      users: true

    teams:
      - key: "ENG"
        sync_to_list: 38
      - key: "SUPPORT"
        sync_to_list: 39

    issue_states:
      - Backlog
      - Todo
      - "In Progress"
      - Done
      - Canceled
```

### Feldzuordnung

Ordne Linear-Nutzer:innen- und Issue-Daten Brevo-Attributen zu:

```yaml
field_mapping:
  # User fields
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Issue metrics mapped to contact events
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Project data
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM
```

### Event-Zuordnung

```yaml
event_mapping:
  Issue.create: ISSUE_CREATED
  Issue.update: ISSUE_UPDATED
  Issue.remove: ISSUE_DELETED
  Comment.create: COMMENT_ADDED
  Project.update: PROJECT_UPDATED
  Cycle.update: CYCLE_UPDATED
```

## API-Endpunkte

Linear nutzt einen einzigen GraphQL-Endpunkt. Zentrale Queries und Mutations, die Tajo verwendet:

| Operation | Typ | Zweck |
| --- | --- | --- |
| `issues` | Query | Issues auflisten und filtern |
| `issue` | Query | Einzelnes Issue per ID abrufen |
| `projects` | Query | Alle Projekte auflisten |
| `cycles` | Query | Cycles (Sprints) auflisten |
| `teams` | Query | Workspace-Teams auflisten |
| `users` | Query | Workspace-Mitglieder auflisten |
| `viewer` | Query | Informationen zur:zum authentifizierten Nutzer:in abrufen |
| `issueCreate` | Mutation | Neues Issue erstellen |
| `issueUpdate` | Mutation | Bestehendes Issue aktualisieren |
| `commentCreate` | Mutation | Kommentar zu einem Issue hinzufügen |
| `webhookCreate` | Mutation | Webhook registrieren |

### Beispiel-GraphQL-Query

```graphql
query GetIssues($filter: IssueFilter, $first: Int, $after: String) {
  issues(filter: $filter, first: $first, after: $after) {
    nodes {
      id
      identifier
      title
      state { name }
      priority
      assignee { email name }
      labels { nodes { name } }
      createdAt
      updatedAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Code-Beispiele

### Connector initialisieren

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('linear', {
  apiKey: process.env.LINEAR_API_KEY
});
```

### Issues synchronisieren

```javascript
await tajo.connectors.sync('linear', {
  type: 'incremental',
  resources: ['issues'],
  teams: ['ENG', 'SUPPORT'],
  since: '2024-01-01'
});

const status = await tajo.connectors.status('linear');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T18:00:00Z',
//   issuesTracked: 3200,
//   projectsMonitored: 8,
//   usersLinked: 45
// }
```

### Linear-Webhooks verarbeiten

```javascript
app.post('/webhooks/linear', async (req, res) => {
  const event = req.body;

  // Verify webhook signature
  const signature = req.get('Linear-Signature');
  if (!verifyLinearSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('linear', {
    type: event.type,
    action: event.action,
    payload: {
      issueId: event.data?.id,
      identifier: event.data?.identifier,
      title: event.data?.title,
      state: event.data?.state?.name,
      assigneeEmail: event.data?.assignee?.email
    }
  });

  res.status(200).send('OK');
});
```

### Issue aus Brevo-Event erstellen

```javascript
// Create a Linear issue when a Brevo contact submits a request
tajo.events.on('contact.event', async (event) => {
  if (event.name === 'FEATURE_REQUEST') {
    await tajo.connectors.create('linear', {
      teamId: 'ENG',
      title: `Feature Request: ${event.data.subject}`,
      description: event.data.description,
      priority: 3,
      labelIds: ['feature-request']
    });
  }
});
```

## Ratenbegrenzungen

Linear erzwingt Ratenbegrenzungen auf seiner GraphQL-API:

| Limit-Typ | Wert |
| --- | --- |
| **Anfragerate** | 1.500 Anfragen pro Stunde pro API-Key |
| **Query-Komplexität** | 10.000 Komplexitätspunkte pro Anfrage |
| **Paginierung** | Max. 250 Nodes pro Seite (Standard 50) |
| **Webhooks** | Unbegrenzt eingehende Events |

Komplexitätsbudget

Linear verwendet ein komplexitätsbasiertes Rate-Limiting-System. Einfachere Queries kosten weniger Punkte. Tajo optimiert Queries, um die Komplexität zu minimieren, indem nur benötigte Felder angefordert und effiziente Paginierung verwendet wird.

Linear liefert `429 Too Many Requests` mit einem `Retry-After`-Header zurück, wenn Limits überschritten werden.

## Fehlerbehebung

### Häufige Probleme

| Problem | Ursache | Lösung |
| --- | --- | --- |
| 401 Unauthorized | Ungültiger oder widerrufener API-Key | Neuen API-Key in den Linear-Einstellungen generieren |
| Query-Fehler | Ungültige GraphQL-Syntax | Queries mit dem Linear-API-Explorer validieren |
| Fehlende Issues | Team-Zugriff eingeschränkt | Sicherstellen, dass der/die API-Key-Inhaber:in Zugriff auf Ziel-Teams hat |
| Webhook wird nicht ausgelöst | Falsche URL oder deaktiviert | Webhook-Status in Linear-Settings > API > Webhooks prüfen |
| Paginierung unvollständig | Fehlender `after`-Cursor | Sicherstellen, dass die Paginierung läuft, bis `hasNextPage` false ist |

### Debug-Modus

```yaml
connectors:
  linear:
    debug: true
    log_level: verbose
    log_queries: true
```

### Verbindung testen

```bash
tajo connectors test linear
# ✓ GraphQL API connection successful
# ✓ Workspace access verified
# ✓ Team list readable
# ✓ Issue query operational
# ✓ Webhook registration available
```

## Best Practices

1. **Webhooks für Echtzeit nutzen** - Registriere Webhooks statt auf Issue-Änderungen zu pollen
2. **Nach Team filtern** - Synchronisiere nur Issues aus relevanten Teams, um die API-Nutzung zu reduzieren
3. **GraphQL-Queries optimieren** - Fordere nur benötigte Felder an, um innerhalb der Komplexitätslimits zu bleiben
4. **Labels in Segmente überführen** - Nutze Linear-Labels für die Brevo-Kontaktsegmentierung
5. **Paginierung handhaben** - Prüfe stets `hasNextPage` und verwende `endCursor` für vollständige Daten
6. **Webhook-Signaturen prüfen** - Validiere stets den `Linear-Signature`-Header

## Sicherheit

- **API-Key-Authentifizierung** - Persönliche Keys auf den Workspace beschränkt
- **OAuth 2.0** - Sicherer Autorisierungs-Flow für Integrationen über mehrere Workspaces
- **Nur HTTPS** - Die gesamte API-Kommunikation ist per TLS 1.2+ verschlüsselt
- **Webhook-Signaturen** - HMAC-basierte Signaturprüfung
- **Verschlüsselte Speicherung** - API-Keys werden in Tajo verschlüsselt gespeichert
- **SOC-2-Konformität** - Die Linear-Plattform ist SOC-2-Type-II-zertifiziert

## Verwandte Ressourcen

- [GitHub Connector](https://tajo.io/de/docs/connectors/custom/github)
- [Jira Connector](https://tajo.io/de/docs/connectors/custom/jira)
- [Notion Connector](https://tajo.io/de/docs/connectors/custom/notion)
- [Brevo Contacts API](https://tajo.io/de/docs/contact-management)