Linear konnektor

Csatlakoztasd a Linear munkaterületedet a Brevóhoz ügyfél-oldali hibajegy-követéshez, termékfrissítési értesítésekhez és fejlesztési mérföldkő-kampányokhoz a Tajo segítségével.

Áttekintés

Funkciók

• Hibajegy-esemény szinkronizáció – Hibajegy létrehozási, frissítési és befejezési események továbbítása Brevo kapcsolati idővonalakra
• Projekt mérföldkő-követés – Brevo kampányok indítása, amikor a projektek kulcsfontosságú mérföldköveket érnek el
• Ügyfél hibajegy-összekapcsolás – Linear hibajegyek összekapcsolása Brevo kapcsolatokkal support láthatóságért
• Cimke alapú szegmentálás – Linear cimkék leképezése Brevo kapcsolat-attribútumokhoz
• Ciklus-analitika – Sprint/ciklus befejezési adatok szinkronizálása csapatteljesítmény-riportoláshoz
• Webhook vezérelt automatizálás – Valós idejű esemény-továbbítás Linear webhookok segítségével

Előfeltételek

Mielőtt elkezdenéd, győződj meg róla, hogy rendelkezel:

1. Egy Linear munkaterülettel adminisztrátori hozzáféréssel
2. Egy konfigurált személyes API kulccsal vagy OAuth alkalmazással
3. Egy Brevo fiókkal API-hozzáféréssel
4. Egy Tajo fiókkal aktív előfizetéssel

Hitelesítés

A Linear személyes API kulcsokat és OAuth 2.0-t támogat.

1. lehetőség: Személyes API kulcs

1. Menj a Linear > Settings > API > Personal API keys menüpontra
2. Kattints a Create key gombra
3. Nevezd el „Tajo Integration”-nek
4. Másold ki a generált kulcsot (lin_api_-val kezdődik)

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

2. lehetőség: OAuth 2.0

Több munkaterületet kiszolgáló integrációkhoz:

1. Hozz létre egy OAuth alkalmazást a linear.app/settings/api/applications oldalon
2. Konfiguráld az átirányítási URI-t: https://app.tajo.io/callbacks/linear
3. Kérd a hatóköröket: read, write, issues:create, comments:create

Csatlakozás a Tajóhoz

# 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

Konfiguráció

Alapbeállítás

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

Mezőleképezés

Képezd le a Linear felhasználói és hibajegy-adatokat Brevo attribútumokhoz:

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

Esemény-leképezés

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 végpontok

A Linear egyetlen GraphQL végpontot használ. A Tajo által használt főbb lekérdezések és mutációk:

GraphQL lekérdezési példa

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
    }
  }
}

Kódpéldák

A konnektor inicializálása

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
});

Hibajegyek szinkronizálása

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 webhookok kezelése

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');
});

Hibajegy létrehozása Brevo eseményből

// 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']
    });
  }
});

Ráta-korlátok

A Linear ráta-korlátokat alkalmaz a GraphQL API-jára:

A Linear 429 Too Many Requests választ ad vissza a Retry-After fejléccel a korlátok túllépésekor.

Hibaelhárítás

Gyakori problémák

Hibakeresési mód

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

Kapcsolat tesztelése

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

Legjobb gyakorlatok

1. Valós idejűséghez használj webhookokat – Regisztrálj webhookokat a hibajegy-változásokhoz lekérdezés helyett
2. Szűrj csapat szerint – Csak a releváns csapatok hibajegyeit szinkronizáld az API-használat csökkentéséhez
3. Optimalizáld a GraphQL lekérdezéseket – Csak a szükséges mezőket kérd a komplexitási korlátokon belül maradva
4. Képezd le a cimkéket szegmensekre – Használd a Linear cimkéket a Brevo kapcsolat-szegmentálás vezérléséhez
5. Kezelj oldalazást – Mindig ellenőrizd a hasNextPage értékét és használd az endCursor értéket az adatok teljességéhez
6. Ellenőrizd a webhook aláírásokat – Mindig validáld a Linear-Signature fejlécet

Biztonság

• API kulcs hitelesítés – Munkaterületre korlátozott személyes kulcsok
• OAuth 2.0 – Biztonságos engedélyezési folyam több munkaterületes integrációkhoz
• Csak HTTPS – Minden API kommunikáció TLS 1.2+-on keresztül titkosítva
• Webhook aláírások – HMAC alapú aláírás-ellenőrzés
• Titkosított tárolás – Az API kulcsok titkosítva tárolódnak a Tajóban
• SOC 2 megfelelőség – A Linear platform SOC 2 Type II tanúsítvánnyal rendelkezik

Kapcsolódó források

• GitHub konnektor
• Jira konnektor
• Notion konnektor
• Brevo Contacts API