--- title: "Connecteur Linear" description: "Guide complet d'intégration Linear pour synchroniser issues, projets et données d'activité d'équipe avec Brevo via Tajo." url: https://tajo.io/fr/docs/connectors/custom/linear/ markdown: https://tajo.io/fr/docs/connectors/custom/linear.md lang: fr-FR robots: noindex --- Demandez un accès anticipé Indiquez votre prénom et votre adresse e-mail professionnelle. Nous vous enverrons un lien pour confirmer votre demande d’accès à Tajo. # Connecteur Linear Statut du connecteur: Prévu Pas encore construit. Tajo n'exécute pas ce connecteur aujourd'hui. | Champ source | Champ de destination | Valeur d’exemple | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | 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 | Propriété | Valeur | | --- | --- | | **Plateforme** | Linear | | **Catégorie** | Custom | | **Complexité d’installation** | Facile | | **Intégration officielle** | Non | | **Données synchronisées** | Issues, projets, utilisateurs, événements | | **Type d’API** | API GraphQL | | **Authentification** | OAuth 2.0 / Personal API Key | | **URL de base** | `https://api.linear.app/graphql` | ## 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_`) ```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 Pour les intégrations servant plusieurs workspaces : 1. Créez une application OAuth sur [linear.app/settings/api/applications](https://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` API GraphQL Linear utilise exclusivement une API GraphQL. Toutes les queries et mutations passent par un endpoint unique : `https://api.linear.app/graphql`. Tajo gère automatiquement la construction des requêtes GraphQL. ### Connexion à Tajo ```bash # 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 ```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 ``` ### Mappage des champs Mappez les données utilisateur et issue Linear vers les attributs Brevo : ```yaml 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 ```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 ``` ## Endpoints API Linear utilise un endpoint GraphQL unique. Principales queries et mutations utilisées par Tajo : | Opération | Type | Objet | | --- | --- | --- | | `issues` | Query | Lister et filtrer les issues | | `issue` | Query | Obtenir une issue par ID | | `projects` | Query | Lister tous les projets | | `cycles` | Query | Lister les cycles (sprints) | | `teams` | Query | Lister les équipes du workspace | | `users` | Query | Lister les membres du workspace | | `viewer` | Query | Obtenir les infos de l’utilisateur authentifié | | `issueCreate` | Mutation | Créer une nouvelle issue | | `issueUpdate` | Mutation | Mettre à jour une issue existante | | `commentCreate` | Mutation | Ajouter un commentaire à une issue | | `webhookCreate` | Mutation | Enregistrer un webhook | ### Exemple de requête GraphQL ```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 ```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 }); ``` ### Synchroniser les issues ```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 // } ``` ### Gérer les webhooks Linear ```javascript 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 ```javascript // 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 : | Type de limite | Valeur | | --- | --- | | **Débit de requêtes** | 1 500 requêtes par heure par clé API | | **Complexité de requête** | 10 000 points de complexité par requête | | **Pagination** | 250 nœuds max par page (50 par défaut) | | **Webhooks** | Événements entrants illimités | Budget de complexité Linear utilise un système de limitation basé sur la complexité. Les requêtes simples coûtent moins de points. Tajo optimise les requêtes pour minimiser la complexité en ne demandant que les champs nécessaires et en utilisant une pagination efficace. 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 | Problème | Cause | Solution | | --- | --- | --- | | 401 Unauthorized | Clé API invalide ou révoquée | Générez une nouvelle clé API dans les Settings Linear | | Erreurs de requête | Syntaxe GraphQL invalide | Validez les requêtes avec l’API explorer de Linear | | Issues manquantes | Accès aux équipes restreint | Assurez-vous que le propriétaire de la clé API a accès aux équipes cibles | | Webhook qui ne se déclenche pas | URL incorrecte ou désactivé | Vérifiez le statut du webhook dans Linear Settings > API > Webhooks | | Pagination incomplète | Curseur `after` manquant | Assurez-vous que la boucle de pagination continue jusqu’à ce que `hasNextPage` soit false | ### Mode debug ```yaml connectors: linear: debug: true log_level: verbose log_queries: true ``` ### Tester la connexion ```bash 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](https://tajo.io/fr/docs/connectors/custom/github) - [Connecteur Jira](https://tajo.io/fr/docs/connectors/custom/jira) - [Connecteur Notion](https://tajo.io/fr/docs/connectors/custom/notion) - [API Contacts Brevo](https://tajo.io/fr/docs/contact-management)