Linear Bağlayıcısı

Müşteriye yönelik sorun takibi, ürün güncelleme bildirimleri ve geliştirme kilometre taşı kampanyaları için Linear çalışma alanınızı Tajo üzerinden Brevo’ya bağlayın.

Genel Bakış

Özellikler

• Sorun olayı senkronizasyonu - Sorun oluşturma, güncelleme ve tamamlama olaylarını Brevo kişi zaman çizelgelerine iletin
• Proje kilometre taşı takibi - Projeler önemli kilometre taşlarına ulaştığında Brevo kampanyalarını tetikleyin
• Müşteri sorun bağlantısı - Destek görünürlüğü için Linear sorunlarını Brevo kişileriyle ilişkilendirin
• Etiket tabanlı segmentasyon - Linear etiketlerini Brevo kişi özniteliklerine eşleyin
• Döngü analitiği - Takım performans raporlaması için sprint/döngü tamamlama verilerini senkronize edin
• Webhook tabanlı otomasyon - Linear webhook’ları aracılığıyla gerçek zamanlı olay yönlendirme

Ön Koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

1. Yönetici erişimi olan bir Linear çalışma alanı
2. Yapılandırılmış bir Kişisel API anahtarı veya OAuth uygulaması
3. API erişimi olan bir Brevo hesabı
4. Etkin aboneliği olan bir Tajo hesabı

Kimlik Doğrulama

Linear, Kişisel API anahtarlarını ve OAuth 2.0’ı destekler.

Seçenek 1: Kişisel API Anahtarı

1. Linear > Settings > API > Personal API keys bölümüne gidin
2. Create key öğesine tıklayın
3. Adını “Tajo Integration” olarak belirleyin
4. Oluşturulan anahtarı kopyalayın (lin_api_ ile başlar)

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

Seçenek 2: OAuth 2.0

Birden fazla çalışma alanına hizmet veren entegrasyonlar için:

1. linear.app/settings/api/applications adresinde bir OAuth uygulaması oluşturun
2. Yönlendirme URI’sini yapılandırın: https://app.tajo.io/callbacks/linear
3. Kapsamları isteyin: read, write, issues:create, comments:create

Tajo’ya Bağlanma

# Kişisel API Anahtarı kullanarak
tajo connectors install linear \
  --api-key $LINEAR_API_KEY

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

Yapılandırma

Temel Kurulum

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

Alan Eşleştirme

Linear kullanıcı ve sorun verilerini Brevo özniteliklerine eşleyin:

field_mapping:
  # Kullanıcı alanları
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Kişi olaylarına eşlenen sorun metrikleri
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Proje verileri
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM

Olay Eşleştirme

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 Uç Noktaları

Linear tek bir GraphQL uç noktası kullanır. Tajo tarafından kullanılan temel sorgular ve mutasyonlar:

Örnek GraphQL Sorgusu

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

Kod Örnekleri

Bağlayıcıyı Başlatma

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

Sorunları Senkronize Etme

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 Webhook’larını İşleme

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

  // Webhook imzasını doğrula
  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');
});

Brevo Olayından Sorun Oluşturma

// Bir Brevo kişisi istek gönderdiğinde Linear sorunu oluştur
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']
    });
  }
});

Hız Sınırları

Linear, GraphQL API’sinde hız sınırları uygular:

Sınırlar aşıldığında Linear, Retry-After başlığıyla birlikte 429 Too Many Requests döndürür.

Sorun Giderme

Yaygın Sorunlar

Hata Ayıklama Modu

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

Bağlantı Testi

tajo connectors test linear
# ✓ GraphQL API bağlantısı başarılı
# ✓ Çalışma alanı erişimi doğrulandı
# ✓ Takım listesi okunabilir
# ✓ Sorun sorgusu çalışır durumda
# ✓ Webhook kaydı kullanılabilir

En İyi Uygulamalar

1. Gerçek zamanlı için webhook kullanın - Sorun değişiklikleri için yoklama yerine webhook’ları kaydedin
2. Takıma göre filtreleyin - API kullanımını azaltmak için yalnızca ilgili takımların sorunlarını senkronize edin
3. GraphQL sorgularını optimize edin - Karmaşıklık sınırları içinde kalmak için yalnızca gerekli alanları isteyin
4. Etiketleri segmentlere eşleyin - Brevo kişi segmentasyonunu yönlendirmek için Linear etiketlerini kullanın
5. Sayfalamayı yönetin - Eksiksiz veri için her zaman hasNextPage değerini kontrol edin ve endCursor kullanın
6. Webhook imzalarını doğrulayın - Linear-Signature başlığını her zaman doğrulayın

Güvenlik

• API Anahtarı Kimlik Doğrulaması - Çalışma alanına kapsamlandırılmış kişisel anahtarlar
• OAuth 2.0 - Çoklu çalışma alanı entegrasyonları için güvenli yetkilendirme akışı
• Yalnızca HTTPS - Tüm API iletişimi TLS 1.2+ ile şifrelenir
• Webhook İmzaları - HMAC tabanlı imza doğrulama
• Şifreli Depolama - API anahtarları Tajo’da şifreli olarak saklanır
• SOC 2 Uyumluluğu - Linear platformu SOC 2 Type II sertifikalıdır

İlgili Kaynaklar

• GitHub Bağlayıcısı
• Jira Bağlayıcısı
• Notion Bağlayıcısı
• Brevo Kişiler API