Connecteur Linear

Connectez votre workspace Linear à Brevo pour le suivi des issues côté client, les notifications de mises à jour produit et les campagnes de jalons de développement via Tajo.

Vue d’ensemble

Fonctionnalités

• Synchronisation d’événements issue, Transférez les événements de création, mise à jour et clôture d’issues vers les timelines de contacts Brevo
• Suivi des jalons de projet, Déclenchez des campagnes Brevo lorsque les projets atteignent des jalons clés
• Liaison issues-clients, Associez les issues Linear aux contacts Brevo pour la visibilité support
• Segmentation basée sur les labels, Mappez les labels Linear aux attributs de contact Brevo
• Analytics de cycles, Synchronisez les données de clôture de sprint/cycle pour le reporting de performance d’équipe
• Automatisation pilotée par webhook, Transfert d’événements en temps réel via les webhooks Linear

Prérequis

Avant de commencer, assurez-vous de disposer de :

1. Un workspace Linear avec accès admin
2. Une Personal API key ou application OAuth configurée
3. Un compte Brevo avec accès API
4. Un compte Tajo avec un abonnement actif

Authentification

Linear prend en charge les Personal API keys et OAuth 2.0.

Option 1 : Personal API Key

1. Allez dans Linear > Settings > API > Personal API keys
2. Cliquez sur Create key
3. Nommez-la « Tajo Integration »
4. Copiez la clé générée (commence par 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 } }"}'

Option 2 : OAuth 2.0

Pour les intégrations servant plusieurs workspaces :

1. Créez une application OAuth sur linear.app/settings/api/applications
2. Configurez l’URI de redirection : https://app.tajo.io/callbacks/linear
3. Demandez les scopes : read, write, issues:create, comments:create

Connexion à Tajo

# Avec Personal API Key
tajo connectors install linear \
  --api-key $LINEAR_API_KEY

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

Configuration

Configuration de base

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

Mappage des champs

Mappez les données utilisateur et issue Linear vers les attributs Brevo :

field_mapping:
  # Champs utilisateur
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Métriques d'issue mappées vers des événements de contact
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Données de projet
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM

Mappage des événements

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

Endpoints API

Linear utilise un endpoint GraphQL unique. Principales queries et mutations utilisées par Tajo :

Exemple de requête 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
    }
  }
}

Exemples de code

Initialiser le connecteur

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

Synchroniser les issues

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

Gérer les webhooks Linear

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

  // Vérifier la signature du webhook
  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');
});

Créer une issue depuis un événement Brevo

// Créer une issue Linear lorsqu'un contact Brevo soumet une demande
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']
    });
  }
});

Limites de débit

Linear impose des limites de débit sur son API GraphQL :

Linear renvoie 429 Too Many Requests avec un en-tête Retry-After lorsque les limites sont dépassées.

Dépannage

Problèmes courants

Mode debug

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

Tester la connexion

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

Bonnes pratiques

1. Utilisez les webhooks pour le temps réel, Enregistrez des webhooks plutôt que d’interroger les changements d’issues
2. Filtrez par équipe, Synchronisez uniquement les issues des équipes pertinentes pour réduire l’usage API
3. Optimisez les requêtes GraphQL, Ne demandez que les champs nécessaires pour rester sous les limites de complexité
4. Mappez les labels vers des segments, Utilisez les labels Linear pour piloter la segmentation des contacts Brevo
5. Gérez la pagination, Vérifiez toujours hasNextPage et utilisez endCursor pour des données complètes
6. Vérifiez les signatures de webhook, Validez toujours l’en-tête Linear-Signature

Sécurité

• Authentification par clé API, Clés personnelles limitées au workspace
• OAuth 2.0, Flux d’autorisation sécurisé pour les intégrations multi-workspaces
• HTTPS uniquement, Toutes les communications API chiffrées via TLS 1.2+
• Signatures des webhooks, Vérification de signature basée sur HMAC
• Stockage chiffré, Clés API chiffrées au repos dans Tajo
• Conformité SOC 2, La plateforme Linear est certifiée SOC 2 Type II

Ressources associées

• Connecteur GitHub
• Connecteur Jira
• Connecteur Notion
• API Contacts Brevo