Le service est revenu à la normale, mais l’issue Linear reste ouverte. Sur un autre incident, une notification tardive a rétabli l’ancien statut après la résolution, tandis qu’un commentaire automatique a déclenché une seconde boucle entre les deux outils. Le symptôme n’est pas un simple retard de synchronisation : les équipes ne savent plus quel système décide, qui peut clore le dossier et quelle chronologie fait foi pendant la revue d’incident.
Relier Linear à une plateforme d’incidents paraît direct tant que le flux se résume à « créer un ticket ». La difficulté commence avec les mises à jour : priorité, état, responsable, commentaires, labels, documents et événements techniques n’évoluent pas au même rythme. Copier chaque champ dans les deux sens transforme alors une issue produit en miroir instable du système d’astreinte.
Le bon arbitrage consiste à partager une identité et des décisions, sans imposer un workflow unique. L’outil d’incident possède la détection, l’impact temps réel et le retour du service ; Linear organise l’analyse, le correctif et le travail produit. Contre-intuitivement, ne pas synchroniser un commentaire ou une transition locale peut renforcer la fiabilité en évitant qu’une information de coordination devienne une commande distante.
Une intégration API Linear dédiée doit donc définir l’autorité, la corrélation, les mutations autorisées et le mode de reprise avant le premier webhook. Cette conception s’inscrit dans notre expertise en intégration API, avec des contrats vérifiables par les équipes produit, techniques et opérationnelles.
Donner un rôle distinct à l’incident et à l’issue
L’incident répond à l’urgence : quel service est touché, quel impact existe, quelles mesures sont engagées et quand le fonctionnement redevient acceptable ? L’issue produit répond à une trajectoire : quelle cause corriger, quel changement livrer, qui arbitre et quelle dette reste ouverte ? Les deux objets se complètent, mais leur cycle de vie ne doit pas être confondu.
Un incident peut être résolu après restauration du service alors que l’issue Linear demeure active pour traiter la cause racine. Inversement, une issue peut être annulée parce que le défaut venait d’un fournisseur, sans effacer la chronologie de l’incident. Le mapping commence donc par les décisions attendues, pas par une table mécanique entre noms de statuts.
Cas concret. Une file de messages accumule trente minutes de retard. L’incident passe en surveillance lorsque la file se résorbe, puis en résolu après validation des indicateurs métier. L’issue Linear reste « En cours » jusqu’au déploiement d’un correctif de capacité et à la revue de son effet. La résolution de l’un ne ferme pas automatiquement l’autre.
Choisir l’autorité de chaque état avant le mapping
Une matrice d’autorité attribue chaque décision. La plateforme d’incidents possède la sévérité opérationnelle et l’état de restauration. Linear possède l’équipe, le cycle, le projet, l’estimation et le statut de livraison. Le responsable produit arbitre la priorité du correctif ; le responsable d’incident décide si le service est réellement revenu au niveau attendu.
Les champs partagés restent peu nombreux : identifiant corrélé, titre synthétique, impact, service concerné, lien réciproque et résumé de résolution. Chaque écriture indique sa direction. Une priorité Linear ne remplace pas automatiquement la sévérité d’incident ; elle peut seulement être initialisée selon une règle documentée, puis évoluer indépendamment.
Le signal faible apparaît lorsque les équipes corrigent fréquemment un statut après la synchronisation. Cela révèle une mauvaise attribution de responsabilité, pas un besoin de retry supplémentaire. Avant d’ajouter un nouveau champ, il faut expliquer qui le décide, à quel moment et comment un conflit est résolu.
Corréler durablement incident, issue et service
Le lien repose sur des identifiants stables, jamais sur le titre. Le registre conserve l’identifiant de l’incident source, l’UUID de l’issue Linear, son identifiant lisible, le workspace, l’équipe, le service et la date de création du lien. Les URL facilitent la navigation, mais ne remplacent pas ces clés.
Une contrainte d’unicité empêche deux issues actives pour le même incident et le même type de travail. Si un incident déjà corrélé revient, le connecteur retrouve l’issue existante. Un nouvel incident lié à la même cause peut créer un objet distinct puis référencer l’issue racine, selon la politique produit.
Les fusions et séparations sont explicites. Deux incidents rapprochés ne suppriment pas leurs historiques ; ils pointent vers la décision de fusion. Une issue découpée en plusieurs correctifs conserve le lien initial et ajoute des relations secondaires. Cette structure évite qu’un simple changement de titre casse la réconciliation.
Créer une issue idempotente avec le bon contexte
La mutation de création reçoit l’équipe Linear, le titre, une description minimale et, si nécessaire, un état initial. Lorsque aucun état n’est fourni, Linear place l’issue dans le premier état de la catégorie Backlog, ou dans Triage si cette fonction est activée pour l’équipe. L’intégration ne doit donc pas supposer qu’une création sans stateId signifie « À faire » partout.
Avant l’appel GraphQL, le connecteur réserve la corrélation dans son registre. Après une réponse ambiguë ou un délai dépassé, il recherche le lien avant de relancer. Le résultat de issueCreate doit contenir success et l’issue attendue ; la présence d’un statut HTTP réussi ne suffit pas si le corps GraphQL contient des erreurs.
La description distingue les faits synchronisés du contexte local. Elle expose l’impact, la période, les services et les liens vers les preuves autorisées. Les journaux bruts, secrets et données personnelles ne sont pas copiés. Un modèle stable aide les développeurs sans transformer l’issue en dump technique illisible.
Les mutations créées par l’application doivent rester identifiables. L’acteur OAuth peut apparaître comme l’application, ou comme l’utilisateur qui l’a autorisée selon le mode retenu. Cette attribution permet de distinguer une action humaine d’une mise à jour automatique pendant la revue.
Traduire les états sans forcer deux workflows identiques
Chaque équipe Linear possède ses propres états et identifiants. Le connecteur résout les UUID lors de l’installation ou de la configuration, puis les stocke avec une version de mapping. Il ne cherche pas à chaque mutation un libellé comme « Done », qui peut être renommé, traduit ou utilisé avec un sens différent.
Le mapping est asymétrique. L’ouverture d’un incident peut créer une issue en Triage, tandis que le passage Linear en « En cours » ne change pas l’état opérationnel. La résolution de l’incident ajoute un commentaire et un label, mais la fermeture de l’issue attend éventuellement le correctif livré. Chaque transition autorisée possède son déclencheur et ses préconditions.
Un événement ancien ne doit jamais rouvrir un objet plus récent sans décision métier. Le consommateur compare l’état courant, l’horodatage de l’action et la version enregistrée. Si la transition n’est plus applicable, il journalise l’écart et conserve le statut actuel.
Le rollback porte sur la projection, pas sur l’histoire. Une mauvaise mise à jour est corrigée par une nouvelle mutation tracée. Effacer le commentaire ou modifier directement le registre ferait disparaître la preuve nécessaire pour comprendre la boucle.
Séparer priorité technique et arbitrage produit
La sévérité mesure l’impact immédiat d’un incident ; la priorité Linear ordonne un travail parmi d’autres. Un incident très sévère peut recevoir un correctif déjà déployé et ne plus exiger de grand chantier. Un défaut récurrent de faible intensité peut, au contraire, mériter une priorité produit élevée en raison de son coût cumulé.
Une règle d’initialisation peut traduire une sévérité vers une priorité, mais elle ne reste pas propriétaire du champ. Le responsable produit peut ajuster la valeur et justifier l’écart. La synchronisation conserve la sévérité source séparément, par exemple dans un label ou un champ dédié, sans écraser la décision de backlog.
Le coût caché apparaît quand chaque variation technique remonte automatiquement la priorité. Le backlog devient alors le reflet du bruit d’alerte, et les équipes cessent de lui faire confiance. La méthode préfère une entrée stable, une revue humaine pour les exceptions et une métrique sur le nombre d’incidents rattachés à la même cause.
Synchroniser commentaires et pièces sans dialogue infini
Les commentaires doivent servir une décision transverse : déclaration, changement d’impact, restauration, cause identifiée ou correctif livré. Copier chaque note interne dans les deux sens crée du bruit et peut exposer des données réservées à l’astreinte. Le contrat sélectionne les types de messages et marque leur origine.
Un commentaire créé par le connecteur conserve l’identifiant de l’événement source. Lorsque le webhook Linear correspondant revient, cette origine empêche de le republier vers l’autre système. Les commentaires humains restent locaux sauf action explicite, par exemple une commande ou un label de publication.
Les pièces jointes demandent une attention particulière. Les fichiers hébergés par Linear sont privés et nécessitent une authentification ; une URL copiée hors de Linear n’est pas nécessairement un lien public durable. Le connecteur décide s’il référence la pièce, la transfère vers un stockage autorisé ou laisse uniquement un lien accessible aux utilisateurs habilités.
Cas concret. Le rapport de diagnostic contient un extrait de données client. Il reste dans le coffre de l’outil d’incident, tandis que l’issue Linear reçoit un résumé neutralisé et un lien contrôlé. La communication de résolution n’hérite donc pas d’un document sensible uniquement parce qu’elle partage la même corrélation.
Sécuriser les webhooks Linear et répondre à temps
Vérifier la signature sur le corps brut
Linear signe le corps exact avec HMAC-SHA256 et transmet la valeur dans Linear-Signature. Le récepteur calcule la signature avant de transformer le JSON et effectue une comparaison sûre. Resérialiser l’objet peut changer les octets et invalider une vérification pourtant correcte sur le contenu logique.
Le champ webhookTimestamp permet de limiter le rejeu. La documentation recommande de vérifier qu’il reste proche de l’heure du système, avec une fenêtre d’une minute dans son exemple. Le seuil retenu tient compte de la synchronisation des horloges et ne remplace pas l’idempotence fondée sur Linear-Delivery.
Persister avant le traitement métier
Le point d’entrée doit répondre en moins de cinq secondes avec un statut 200 pour confirmer la livraison. Une réponse lente ou non conforme provoque des tentatives supplémentaires ; la documentation actuelle prévoit au maximum trois retries après environ une minute, une heure puis six heures. Un échec prolongé peut conduire à la désactivation du webhook.
Le handler vérifie, persiste et accuse réception ; un worker traite ensuite l’événement. Le message contient notamment l’action, le type, l’acteur, les données, l’ancien contenu modifié et l’horodatage. L’intégration utilise seulement les champs de son contrat et relit l’issue lorsque la décision nécessite un état complet.
Lire données et erreurs GraphQL sans faux succès
L’API publique Linear utilise GraphQL sur un endpoint unique. Une réponse HTTP 200 peut contenir des données partielles et un tableau errors. Le client vérifie donc les erreurs, leur chemin et leur code avant d’enregistrer la mutation comme réussie. Un champ nul inattendu doit être traité comme une rupture de contrat, pas comme une valeur métier vide.
Les requêtes demandent uniquement les propriétés nécessaires. Après une mutation, récupérer l’UUID, l’identifiant lisible, l’état et la date de mise à jour suffit souvent à confirmer l’effet. Charger commentaires, projet, cycle, labels, utilisateurs et pièces à chaque appel augmente la complexité sans améliorer la preuve.
Le schéma GraphQL évolue sans version REST globale. Linear utilise les dépréciations du schéma et son journal de changements. Une vérification de schéma en intégration continue détecte les champs dépréciés, tandis que les requêtes critiques sont couvertes par des tests contre un workspace de recette.
Paginer et filtrer sans aspirer tout le workspace
Les listes suivent une pagination par curseur de style Relay avec first, after et les informations de page. Le consommateur continue tant que hasNextPage reste vrai et réutilise endCursor. Sans argument, les cinquante premiers résultats sont retournés par défaut.
Le rattrapage privilégie un filtre sur les équipes, projets ou dates réellement concernés. Pour récupérer les changements récents, un ordre par updatedAt évite de parcourir tout l’historique trié par création. Les ressources archivées sont exclues par défaut et ne sont incluses que si le scénario de réconciliation l’exige.
Chaque page passe par le même upsert que les webhooks. Une fenêtre chevauchante relit les dernières modifications afin de récupérer un événement perdu. L’identité stable et la version empêchent cette relecture de dupliquer une issue ou de réappliquer une ancienne transition.
Piloter quotas de requêtes et complexité
Linear limite à la fois le nombre de requêtes et la complexité GraphQL. Les réponses exposent des en-têtes de limite, de solde et de réinitialisation. L’intégration les observe au lieu d’attendre une erreur. Lorsqu’une limite est dépassée, le corps GraphQL peut porter le code RATELIMITED.
Les plafonds publiés dépendent du mode d’authentification et peuvent évoluer. La documentation actuelle indique notamment 2 500 requêtes par heure pour une clé API, 5 000 pour une application OAuth et une complexité maximale de 10 000 points pour une seule requête. Ces valeurs sont relues au moment du développement et ne deviennent pas des constantes métier.
La complexité augmente fortement avec les connexions imbriquées et la pagination par défaut. Une requête ciblée pour dix issues et quelques champs coûte moins qu’un graphe généraliste récupérant cinquante objets avec toutes leurs relations. Le worker groupe les besoins cohérents, mais évite la requête universelle impossible à prioriser.
Les incidents critiques et la synchronisation de confort ne partagent pas la même file. Une reprise de commentaires historiques ne doit pas consommer le budget nécessaire à une création d’issue urgente. Le backoff respecte l’heure de réinitialisation et conserve l’âge du plus ancien dossier comme indicateur opérationnel.
Choisir un acteur OAuth et des droits proportionnés
Une clé personnelle convient à un script limité, mais elle lie le flux à un utilisateur. Une intégration installée dans plusieurs workspaces utilise OAuth2. Les droits commencent par la lecture ; la création d’issues ou de commentaires peut utiliser des scopes ciblés, tandis que le scope administrateur ne doit être demandé que pour des fonctions qui l’exigent réellement.
Par défaut, les mutations OAuth apparaissent comme l’utilisateur qui a autorisé l’application. Le mode d’autorisation avec acteur applicatif permet de faire apparaître les actions comme celles de l’intégration, ce qui convient aux comptes de service. Ce choix est visible dans l’historique et doit correspondre à la responsabilité réelle.
Les jetons et secrets de webhook suivent des rotations séparées. Une révocation OAuth suspend les mutations, alerte l’exploitation et conserve les événements en attente. Le runbook décrit la réautorisation sans demander de copier un jeton personnel dans la configuration de production.
Déployer par équipe avec comparaison et repli
Le pilote commence sur une seule équipe Linear, un type d’incident et quelques transitions. La création peut être active tandis que les mises à jour restent en observation. Le connecteur calcule ce qu’il aurait modifié, compare la décision au traitement humain et conserve les divergences sans écrire.
La bascule ouvre d’abord les mutations réversibles : commentaire de lien, label ou champ de corrélation. Les changements de statut et de priorité viennent ensuite, car ils portent une décision. Chaque palier possède un seuil de divergence et une commande de désactivation indépendante.
Le rollback arrête un sens de synchronisation sans supprimer les liens déjà créés. Les issues restent exploitables manuellement, et la réconciliation peut reprendre après correction. Une note datée indique la dernière version active afin que le support ne confonde pas pause volontaire et panne silencieuse.
Rendre chaque écart explicable par le support
Le support part d’un identifiant d’incident ou d’issue. La vue montre la corrélation, la dernière version, les événements Linear reçus, les mutations émises, les erreurs GraphQL et la prochaine action. Elle distingue signature invalide, rate limit, conflit d’état et règle métier refusée.
Les indicateurs utiles suivent incidents sans issue, issues sans incident, créations en double, transitions ignorées, commentaires en boucle et âge de la quarantaine. Le délai entre l’événement source et la décision appliquée complète la latence API. Un appel rapide qui produit le mauvais état reste un échec.
Deux signaux faibles justifient une revue. Le premier est l’augmentation des corrections humaines juste après les mutations automatiques. Le second est la baisse des erreurs techniques accompagnée d’une hausse des dossiers orphelins. Ces tendances indiquent souvent une divergence de workflow que les métriques HTTP ne voient pas.
Le runbook précise les entrées, sorties, responsabilités, dépendances, seuils et journalisation. Il décrit le retry, la lecture de l’état courant, la réconciliation et le rollback. L’exercice est réussi lorsqu’une personne du support restaure un dossier cohérent sans modifier directement la base ni demander une requête improvisée.
Savoir quand cette intégration produit est utile
Le projet devient utile lorsqu’un incident doit systématiquement alimenter un backlog produit, que plusieurs équipes doivent partager la cause et que le volume rend la copie manuelle peu fiable. Il apporte aussi de la valeur quand les revues exigent une corrélation durable entre alerte, changement, issue et résolution.
Une automatisation simple ou un lien manuel suffit si les incidents restent rares et si la création d’issue demande surtout un jugement humain. Le sur-mesure ne doit pas convertir chaque alerte en tâche. Sans triage, le backlog se remplit plus vite que l’équipe ne peut le qualifier.
Le chantier doit être différé si les états d’incident sont instables, si les équipes Linear n’ont pas de workflow assumé ou si personne ne possède le mapping. La priorité devient alors la clarification des décisions. Connecter deux ambiguïtés ne produit pas une source de vérité.
Erreurs fréquentes qui rouvrent ou dupliquent les issues
- Mapper les libellés au lieu des UUID. Un renommage ou une traduction peut envoyer l’issue vers le mauvais état sans erreur technique visible.
- Créer avant de réserver la corrélation. Un timeout ou deux workers concurrents peuvent alors produire plusieurs issues pour le même incident.
- Rendre tous les champs bidirectionnels. La priorité, le statut et l’assignation se renvoient leurs propres modifications jusqu’à créer une boucle.
- Faire confiance au statut HTTP. Une réponse GraphQL réussie peut contenir des données partielles accompagnées d’erreurs qu’il faut analyser.
- Vérifier la signature après avoir reconstruit le JSON. La signature porte sur le corps brut exact et peut échouer après une sérialisation différente.
- Clore l’issue avec l’incident. Le service peut être restauré tandis que la cause racine et le correctif restent à traiter.
- Copier toutes les pièces et discussions. Cette approche augmente le bruit, les risques d’accès et la charge de synchronisation sans aider la décision.
Décision : périmètre et conditions d’arrêt
La première décision porte sur l’objet déclencheur. Un incident confirmé peut créer une issue, tandis qu’une alerte isolée reste dans l’outil d’observabilité. Cette frontière protège Linear contre le bruit. Le seuil peut combiner durée, impact et validation humaine, selon le fonctionnement réel de l’équipe.
- D’abord, nommer les autorités. Attribuer sévérité, restauration, priorité, livraison et clôture à une équipe et à un système précis.
- Ensuite, réduire le contrat. Partager les identifiants, l’impact, le service, les liens et les décisions indispensables avant d’ajouter commentaires ou pièces.
- Puis, borner les mutations. Commencer par créer et corréler, observer les changements d’état, puis ouvrir uniquement les transitions approuvées.
- Après cela, fixer les seuils. Suspendre le pilote si doublons, boucles, erreurs non expliquées ou quarantaine dépassent la tolérance décidée.
- Enfin, préparer le retrait. Conserver les issues utilisables et les liens consultables si un sens de synchronisation doit être désactivé.
Plan d’action pour un premier flux incident–issue
Cadrer les états et les cas contradictoires
Choisissez une équipe Linear, un service et un type d’incident. Rejouez dix à vingt dossiers récents pour comprendre création, restauration, cause et correctif. Écrivez les cas où l’incident se ferme avant l’issue, où l’issue est annulée et où plusieurs incidents partagent la même cause. Le responsable produit valide les résultats attendus.
Construisez la matrice avec les UUID d’équipe, d’états et de labels. Le contrat définit identifiants, impact, priorité initiale, liens et événements autorisés. Chaque champ possède une source, une direction et une règle de conflit. Les commentaires et fichiers restent hors du premier lot sauf nécessité démontrée.
Implémenter une chaîne vérifiable et réversible
L’entrée vérifie la signature HMAC sur le corps brut, contrôle l’horodatage, déduplique Linear-Delivery et persiste avant de répondre. Le worker utilise une corrélation réservée, inspecte les erreurs GraphQL et journalise la mutation. Les dépendances, timeouts, retries, limites et règles d’idempotence sont explicites.
Ajoutez une réconciliation filtrée par équipe et updatedAt, avec pagination par curseur. Le tableau de bord suit dossiers orphelins, boucles, rate limits, complexité et âge de la quarantaine. Le runbook indique comment relire les deux systèmes, corriger un lien et exécuter un rollback sans effacer la chronologie.
Comparer avant d’autoriser les changements d’état
Le pilote crée l’issue et ajoute les liens, mais calcule seulement les transitions suivantes. L’équipe compare chaque proposition aux décisions humaines pendant une période représentative. Les divergences sont classées : mauvais mapping, état tardif, règle manquante ou choix assumé du produit.
La mise en production ouvre un type de transition à la fois. Elle attend zéro doublon inexpliqué, aucune boucle et une reprise exécutée par le support. Si le seuil de divergence ou le budget de requêtes est dépassé, les mutations sont suspendues tandis que les webhooks continuent d’alimenter l’observation.
Guides complémentaires pour fiabiliser le run
Protéger la réception et l’ordre des événements
La méthode consacrée aux webhooks signés et au blocage du rejeu approfondit la vérification sur corps brut, la rotation des secrets et la séparation entre réception et effet métier.
Les stratégies pour des événements reçus dans le désordre complètent le traitement des mises à jour tardives. Elles aident à conserver l’état actuel sans perdre la trace d’un message devenu inapplicable.
Rendre les mutations explicables et réparables
Le journal d’audit d’une intégration API structure la preuve autour de l’acteur, de la décision, de l’état précédent et de l’effet réellement appliqué.
Enfin, le travail sur l’idempotence et la reprise sur erreur permet de traiter les timeouts ambigus et les doubles livraisons sans multiplier les issues.
- Relire l’autorité des états et les UUID configurés avant chaque extension vers une nouvelle équipe Linear.
- Comparer incidents, issues, versions et événements ignorés pour détecter les divergences avant leur effet produit.
- Faire exécuter une reprise complète par le support sans mutation directe en base avant d’ouvrir un nouveau sens.
Conclusion : synchroniser des responsabilités, pas seulement des statuts
Une intégration Linear utile conserve la différence entre urgence opérationnelle et travail produit. L’incident décrit l’impact et la restauration ; l’issue porte l’analyse, le correctif et la livraison. Une corrélation stable relie les deux sans forcer leur fermeture simultanée.
La fiabilité vient ensuite de choix précis : UUID plutôt que libellés, création idempotente, mutations asymétriques, signature du corps brut, erreurs GraphQL inspectées et pagination filtrée. Les quotas et la complexité deviennent des contraintes pilotées, pas des surprises découvertes pendant une crise.
Le meilleur périmètre reste réduit. Une équipe, un service, un type d’incident et quelques transitions suffisent pour prouver la valeur. Les commentaires, pièces et synchronisations bidirectionnelles ne s’ajoutent qu’après une comparaison réussie et une reprise autonome.
Pour inscrire ce flux dans une démarche d’intégration API sur mesure, notre équipe peut vous accompagner pour cartographier les responsabilités, écrire les contrats Linear et déployer un pilote observable, réconciliable et réversible.
