Konektor Linear

Hubungkan workspace Linear Anda ke Brevo untuk pelacakan issue yang menghadap pelanggan, notifikasi pembaruan produk, dan kampanye milestone pengembangan melalui Tajo.

Ikhtisar

Fitur

• Sinkronisasi event issue - Teruskan event pembuatan, pembaruan, dan penyelesaian issue ke timeline kontak Brevo
• Pelacakan milestone proyek - Picu kampanye Brevo saat proyek mencapai milestone penting
• Penautan issue pelanggan - Kaitkan issue Linear dengan kontak Brevo untuk visibilitas dukungan
• Segmentasi berbasis label - Petakan label Linear ke atribut kontak Brevo
• Analitik cycle - Sinkronkan data penyelesaian sprint/cycle untuk pelaporan performa tim
• Otomatisasi berbasis webhook - Penerusan event real-time melalui webhook Linear

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

1. Workspace Linear dengan akses admin
2. Personal API key atau aplikasi OAuth yang telah dikonfigurasi
3. Akun Brevo dengan akses API
4. Akun Tajo dengan langganan aktif

Autentikasi

Linear mendukung Personal API key dan OAuth 2.0.

Opsi 1: Personal API Key

1. Buka Linear > Settings > API > Personal API keys
2. Klik Create key
3. Beri nama “Tajo Integration”
4. Salin key yang dihasilkan (diawali dengan lin_api_)

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

Opsi 2: OAuth 2.0

Untuk integrasi yang melayani banyak workspace:

1. Buat aplikasi OAuth di linear.app/settings/api/applications
2. Konfigurasikan redirect URI: https://app.tajo.io/callbacks/linear
3. Minta scope: read, write, issues:create, comments:create

Menghubungkan ke Tajo

# 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

Konfigurasi

Setup dasar

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

Pemetaan field

Petakan data pengguna dan issue Linear ke atribut Brevo:

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

Pemetaan event

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

Endpoint API

Linear menggunakan satu endpoint GraphQL. Query dan mutation utama yang dipakai Tajo:

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

Contoh kode

Inisialisasi konektor

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

Menyinkronkan issue

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

Menangani webhook Linear

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

Membuat issue dari event Brevo

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

Batas rate

Linear menerapkan batas rate pada GraphQL API miliknya:

Linear mengembalikan 429 Too Many Requests dengan header Retry-After saat batas terlampaui.

Pemecahan masalah

Masalah umum

Mode debug

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

Menguji koneksi

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

Praktik terbaik

1. Gunakan webhook untuk real-time - Daftarkan webhook alih-alih melakukan polling untuk perubahan issue
2. Filter berdasarkan tim - Sinkronkan hanya issue dari tim yang relevan untuk mengurangi penggunaan API
3. Optimalkan query GraphQL - Minta hanya field yang dibutuhkan agar tetap dalam batas kompleksitas
4. Petakan label ke segmen - Gunakan label Linear untuk menggerakkan segmentasi kontak Brevo
5. Tangani paginasi - Selalu periksa hasNextPage dan gunakan endCursor untuk data yang lengkap
6. Verifikasi tanda tangan webhook - Selalu validasi header Linear-Signature

Keamanan

• Autentikasi API key - Personal key dibatasi pada lingkup workspace
• OAuth 2.0 - Alur otorisasi aman untuk integrasi multi-workspace
• Hanya HTTPS - Seluruh komunikasi API dienkripsi via TLS 1.2+
• Tanda tangan webhook - Verifikasi tanda tangan berbasis HMAC
• Penyimpanan terenkripsi - API key dienkripsi saat disimpan di Tajo
• Kepatuhan SOC 2 - Platform Linear bersertifikat SOC 2 Type II

Sumber daya terkait

• Konektor GitHub
• Konektor Jira
• Konektor Notion
• Brevo Contacts API