Mise à jour automatique d'app Electron : guide pratique 2026

Vous avez déployé le build Electron, la page de release est en ligne, et le premier ticket de support arrive avant même que la machine à café ne soit chaude. Un utilisateur explique que l'app n'a jamais trouvé la mise à jour. Un autre l'a téléchargée mais ne peut pas l'installer. Un troisième tourne encore sur un ancien binaire avec un flux d'authentification cassé, alors que vos logs n'affichent presque rien d'utile.

C'est la réalité inconfortable de l'auto-update d'app Electron. L'updater API n'est qu'un composant parmi d'autres. Une release en production dépend aussi de la signature de la plateforme, de la politique de transport, des manifests, de l'hébergement, des événements de cycle de vie, de l'observabilité, des contrôles de déploiement progressif et d'un chemin de rollback. Traitez l'un de ces éléments comme optionnel et un patch de routine peut se transformer en incident en pleine nuit.

Table des matières

• L'incident de mise à jour de 2 h du matin à l'origine de ce guide
• Choisir la bonne approche pour l'updater Electron
• Implémenter le flux d'auto-update dans le processus principal
  • Configurer d'abord la cible de publication
  • Schedule checks and expose lifecycle events
  • Informer le renderer sans bloquer le travail
• Configurer la CI/CD pour les releases signées et les manifests
  • Rendre la signature explicite dans la CI
• Déploiements progressifs, canaux et stratégie de rollback
  • Utilisez des cohortes avant une exposition large
• Considérer l'auto-update comme un contrôle de sécurité
  • Protéger les métadonnées avec autant de soin que le binaire
• Guide et checklist de mise à jour en production
  • Points de contrôl’avant release
  • Canary et déploiement complet
  • Réponse aux incidents

L'incident de mise à jour de 2 h du matin à l'origine de ce guide

La release a passé le CI et semblait banale. En fin de semaine, un développeur a poussé un build Electron non signé, et le job de publication a uploadé suffisamment d’assets pour que la release paraisse complète. L’application a démarré en test, mais personne n’avait exercé le chemin de mise à jour depuis un build de production installé.

À 2 h 08, PagerDuty a alerté l’ingénieur de garde. Un nouveau flux d’authentification a échoué pour une partie de la flotte, et les utilisateurs ayant reçu la mise à jour ne pouvaient pas finaliser leur connexion. D’autres utilisateurs restaient sur la version précédente car le mécanisme de mise à jour ne pouvait ni vérifier ni installer l’artefact. Certains clients avaient une release cassée, tandis que le reste de la flotte tournait sur une version différente, sans explication claire.

L’investigation a suivi cinq vérifications :

1. Vérifier le flux de release. Le binaire existait, mais les métadonnées attendues ne définissaient pas clairement quels clients devaient le recevoir. Un manifeste est un contrat entre le pipeline de release et les clients installés, pas un détail d’upload optionnel.
2. Inspecter la signature. La release n’était pas signée correctement, ce qui a fait échouer la vérification sur les plateformes concernées. La signature doit bloquer la publication lorsqu’elle est manquante ou invalide.
3. Comparer les logs des clients. Les erreurs de mise à jour n'atteignaient jamais la télémétrie centrale. L'application absorbait l'événement et continuait de fonctionner, laissant l'équipe sans preuve fiable.
4. Vérifier les contrôles de déploiement. Il n'y avait ni canal interne ni cohorte de déploiement progressif. Tous les clients éligibles utilisaient le même flux, la défaillance s'est donc propagée sans point de confinement.
5. Rechercher un rollback. L'équipe n'avait aucune procédure testée pour republier la version précédente ou détourner les clients de la release défectueuse.

La documentation officielle d'Electron expose clairement les limites de la plateforme. Linux ne dispose d'aucun support natif de l'auto-updater, et les requêtes de mise à jour macOS doivent respecter les exigences d'App Transport SecurityLa documentation identifie également la signature comme un prérequis pour des mises à jour macOS fiables et la vérification des releases. La documentation de l'autoUpdater d'Electron définit les contraintes API, tandis que le système de release doit appliquer les contrôles opérationnels associés.

Leçon de postmortem : Un updater incapable d'expliquer ce qui s'est passé est une tentative d'installation à distance sans télémétrie.

Le coût a dépassé le simple temps d'ingénierie. Les clients ont perdu confiance dans le client desktop, le support a dû expliquer des comportements incohérents, et l'équipe a passé la journée de travail suivante à reconstruire un processus de release qui aurait dû exister avant l'incident.

Considérez l'auto-update comme un système opérationnel. La signature est une étape de validation de la release, les manifests définissent le contrat client, les canaux de déploiement limitent l'exposition, et le rollback reste un chemin testé plutôt qu'une solution d'urgence improvisée.

Choisir la bonne approche pour l'updater Electron

À 2 h du matin, un mauvais choix d'updater devient un problème opérationnel. Une mise à jour de binaire natif doit gérer la signature, les manifests, les installateurs et le rollback. Un changement de CSS ou de JavaScript côté renderer suit un chemin différent. Les contraintes d'hébergement comptent aussi : un petit projet hébergé sur GitHub n'a pas besoin des mêmes contrôles de release qu'un service de distribution d'entreprise.

Pour les projets utilisant electron-builder avec publication d'artefacts signés, electron-updater est généralement le choix par défaut le plus pragmatique. Son écosystème couvre les cibles de publication, les manifests de release, le téléchargement d'artefacts et l'installation au prochain lancement. Il prend en charge plusieurs modèles d'hébergement, mais votre équipe reste responsable de la signature, de la disponibilité du flux, de la politique des canaux, des contrôles de déploiement et du monitoring. L' intégration de l'updater Electron pour Capgo est pertinent lors de l’évaluation d’un modèle de livraison hybride pour les bundles de la couche web, en parallèle des releases natives.

update-electron-app convient aux équipes qui souhaitent une intégration légère autour des GitHub Releases. Il vérifie les mises à jour au démarrage puis à intervalle régulier, ce qui simplifie la configuration mais limite les options avancées de sélection de canal, de trafic progressif et de règles de rollback personnalisées. Le package est raisonnable pour un processus de release simple, à condition que les GitHub Releases et leur disponibilité correspondent à vos exigences opérationnelles.

Un service sur mesure comme Hazel, Nuts ou un feed interne est pertinent lorsque l'autorisation des releases, le ciblage par tenant, les journaux d'audit ou les règles de déploiement réglementé justifient le coût d'implémentation. En contrepartie, vous assumez la responsabilité continue : votre équipe doit définir la sémantique des manifests, protéger les clés de signature, préserver la compatibilité client et tester les téléchargements échoués, les releases rejetées et le comportement en cas de rollback.

Les live updates permettent de déployer des modifications limitées au renderer sans recompiler le shell natif. Elles ne remplacent pas les mises à jour binaires lorsque Electron, les modules natifs, les permissions ou le comportement de l’installateur changent. Use electron-updater unless you need custom rollout logic. Si une logique personnalisée est requise, construisez-l’autour des conventions établies pour les manifests et les artefacts, plutôt que de recréer le téléchargement et les mises à jour différentielles. La voie la plus fiable est celle que votre équipe peut observer, déployer progressivement et annuler sous pression.

Implémenter le flux d'auto-update dans le processus principal

Le processus principal doit gérer les vérifications de mise à jour et l’installation. Le renderer peut afficher l’état, mais il ne doit pas décider si une mise à jour exécutable est fiable ni quand l’application se ferme.

Configurer d'abord la cible de publication

Une configuration minimale d’electron-builder pourrait ressembler à ceci :

{
  "build": {
    "appId": "com.example.desktop",
    "publish": [
      {
        "provider": "s3",
        "bucket": "example-electron-releases",
        "channel": "stable"
      }
    ],
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    }
  }
}

Gardez les flux beta et stable séparés. Un canal est une politique de release, pas un simple libellé dans l’interface. Chaque canal doit pointer vers le bon artefact signé et le bon manifeste.

Schedule checks and expose lifecycle events

Appeler checkForUpdates() Ne vérifier que au démarrage est une erreur courante en production. Un utilisateur peut laisser l’application ouverte pendant des jours, le processus principal doit donc disposer d’un intervalle contrôlé et d’une stratégie de retry qui respecte le mode hors ligne.

const { app, BrowserWindow, ipcMain } = require('electron');
const { autoUpdater } = require('electron-updater');

let mainWindow;
let isQuitting = false;
let retryDelay = 60 * 1000;

function sendUpdateStatus(status, payload = {}) {
  if (mainWindow && !mainWindow.isDestroyed()) {
    mainWindow.webContents.send('update-status', { status, ...payload });
  }
}

function scheduleUpdateCheck() {
  setTimeout(async () => {
    try {
      await autoUpdater.checkForUpdates();
      retryDelay = 60 * 1000;
    } catch (error) {
      sendUpdateStatus('error', { message: error.message });
      retryDelay = Math.min(retryDelay * 2, 30 * 60 * 1000);
    }
    scheduleUpdateCheck();
  }, retryDelay);
}

app.whenReady().then(() => {
  mainWindow = new BrowserWindow({
    webPreferences: {
      preload: require('path').join(__dirname, 'preload.js')
    }
  });

  autoUpdater.autoDownload = true;
  autoUpdater.autoInstallOnAppQuit = false;

  autoUpdater.on('checking-for-update', () => {
    sendUpdateStatus('checking');
  });

  autoUpdater.on('update-available', info => {
    sendUpdateStatus('available', { version: info.version });
  });

  autoUpdater.on('download-progress', progress => {
    sendUpdateStatus('progress', { percent: progress.percent });
  });

  autoUpdater.on('update-downloaded', info => {
    sendUpdateStatus('downloaded', { version: info.version });
  });

  autoUpdater.on('error', error => {
    sendUpdateStatus('error', { message: error.message });
  });

  autoUpdater.checkForUpdates().catch(error => {
    sendUpdateStatus('error', { message: error.message });
  });

  scheduleUpdateCheck();
});

ipcMain.handle('install-update', () => {
  isQuitting = true;
  autoUpdater.quitAndInstall(false, true);
});

app.on('before-quit', event => {
  if (!isQuitting) {
    return;
  }
});

Le comportement exact des événements de mise à jour dépend de la plateforme et de la configuration de packaging ; testez donc à partir d’artefacts installés, pas en mode développement. La documentation d’Electron signale aussi des problèmes de timing au démarrage sous Windows, notamment le cas du premier lancement de Squirrel. Ne lancez pas de vérification de mise à jour avant que l’application ait terminé l’initialisation spécifique à la plateforme requise.

Informer le renderer sans bloquer le travail

Le pont preload doit exposer une API restreinte :

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('updates', {
  onStatus(callback) {
    ipcRenderer.on('update-status', (_event, status) => callback(status));
  },
  install() {
    return ipcRenderer.invoke('install-update');
  }
});

Une barre de progression côté renderer peut rester volontairement simple :

window.updates.onStatus(status => {
  const progress = document.querySelector('#update-progress');
  const message = document.querySelector('#update-message');

  if (status.status === 'progress') {
    progress.hidden = false;
    progress.value = status.percent;
    message.textContent = `Downloading update, ${Math.round(status.percent)}%`;
  }

  if (status.status === 'downloaded') {
    message.textContent = `Version ${status.version} is ready to install`;
  }

  if (status.status === 'error') {
    message.textContent = 'The update could not be downloaded. We will retry later.';
  }
});

Conditionnez l'installation au consentement de l'utilisateur en production, sauf si votre application a une bonne raison de redémarrer immédiatement. Définissez un isQuitting flag avant quitAndInstall(), car sinon les gestionnaires de fermeture de fenêtre habituels peuvent empêcher l'installateur de prendre le relais.

Deux échecs méritent des tests explicites. Premièrement, un client déjà en cours d'exécution doit appeler checkForUpdates() de façon planifiée, et pas seulement au lancement. Deuxièmement, le error doit remonter dans les logs et la télémétrie. Si l'app l'ignore sans le signaler, votre workflow de dépannage de l'app commence par des suppositions plutôt que par des preuves.

Configurer la CI/CD pour les releases signées et les manifests

Le pipeline de release est la source de vérité pour ce que les utilisateurs installent. Un build local qui fonctionne sur la machine d'un développeur ne prouve pas que le binaire, le manifest, la signature et le canal publiés décrivent tous la même release.

Le modèle de publication d'electron-builder exige que les métadonnées de la release et la cible de mise à jour voyagent ensemble. Pour de nombreuses configurations, cela signifie un artefact tel que latest.yml pour Windows et latest-mac.yml pour macOS, aux côtés des packages spécifiques à la plateforme et des fichiers blockmap. Un manifeste manquant peut rendre un binaire parfaitement valide invisible pour les clients.

Rendre la signature explicite dans la CI

Un pattern GitHub Actions simplifié ressemble à ceci :

name: release

on:
  push:
    tags:
      - "v*"

jobs:
  build:
    strategy:
      matrix:
        os: [macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run test
      - run: npm run build

      - name: Build and publish
        shell: bash
        env:
          CSC_LINK: ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
          WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: npx electron-builder --publish always

Utilisez des secrets spécifiques à la plateforme et gardez les éléments de signature en dehors du dépôt. Un échec de signature doit arrêter le job, et non produire un fallback non signé que quelqu'un enverrait manuellement.

La configuration de publication doit identifier le fournisseur et le canal de manière cohérente :

{
  "build": {
    "publish": {
      "provider": "s3",
      "bucket": "example-electron-releases",
      "channel": "stable",
      "publishAutoUpdate": true,
      "updaterCacheDirName": "example-desktop-updater"
    }
  }
}

Avant la publication, conditionnez le job à la version du package, au tag, au SHA du commit et au résultat du smoke test. Après publication, vérifiez que le feed contient le manifeste attendu et que ce dernier pointe vers l’artefact exact généré par ce job. Le guide de configuration de l'intégration continue est utile lorsque vous formalisez ces contrôles, et les équipes qui comparent l’orchestration de pipelines peuvent également en tirer profit quand utiliser Jenkins et Ansible ensemble.

Les commandes qui révèlent le plus souvent une release incomplète sont volontairement basiques :

npx electron-builder --publish never
test -f dist/latest.yml
test -f dist/latest-mac.yml
find dist -name "*.blockmap" -print

Ces vérifications ne remplacent pas un test d’installation signé. Elles détectent en revanche l’erreur opérationnelle consistant à envoyer un binaire sans les métadonnées dont les clients ont besoin pour le découvrir.

Déploiements progressifs, canaux et stratégie de rollback

Un flux de release doit se comporter davantage comme une cible de déploiement que comme un dossier de téléchargement. Gardez interne, bêta, et Dernière les canaux sont séparés, chaque canal reposant sur son propre manifeste et son propre ensemble d'artefacts signés. La promotion doit faire passer une release testée d'une politique à l'autre, et non écraser un fichier pendant que les clients le téléchargent.

La séparation des canaux protège aussi la production des builds de test accidentels. L'updater doit savoir si un client appartient à une cohorte interne, à une audience bêta ou à la population stable avant d'évaluer le flux.

Utilisez des cohortes avant une exposition large

Un champ de manifeste personnalisé peut exprimer un déploiement progressif :

version: 4.8.0
path: Example-Setup-4.8.0.exe
sha512: signed-artifact-hash
rolloutPercentage: 10

Le processus principal peut attribuer un bucket stable par utilisateur, puis comparer ce bucket avec rolloutPercentage. Une attribution stable est essentielle. Un utilisateur qui bascule entre éligible et non éligible à chaque vérification aura un comportement imprévisible et rendra les rapports de support difficiles à interpréter.

Élargissez la cohorte seulement après que la release a franchi sa fenêtre d'observation. La fenêtre exacte doit refléter votre usage réel, mais la décision doit reposer sur des signaux, pas seulement sur un calendrier. Suivez les résultats des vérifications de mise à jour, les téléchargements aboutis, la santé au démarrage, les crashs, les exceptions du renderer et les authentifications réussies.

Ne confondez pas un rollback avec la suppression d’un artefact. Certains clients peuvent avoir mis en cache les métadonnées, et d’autres peuvent déjà exécuter la version défectueuse. Un plan de rollback nécessite une release signée précédente, une modification du feed et un comportement client capable de récupérer.

Règle opérationnelle : Le rollback doit pouvoir être exécuté par l'ingénieur d'astreinte sans avoir à recompiler l'application pendant l'incident.

En pratique, le runbook doit promouvoir à nouveau le manifeste de la version précédente sur le canal affecté, invalider le marqueur de staging et confirmer que les nouvelles vérifications pointent vers la version sûre. Si le problème se situe dans le code du renderer plutôt que dans le shell natif, un rollback ciblé de la couche web peut être plus rapide. Une plateforme telle que Capgo déploiements progressifs peut être pertinente pour cette couche de livraison distincte, mais elle ne doit pas masquer la frontière entre un rollback de binaire natif et un rollback de bundle web.

Considérer l'auto-update comme un contrôle de sécurité

Un updater Electron télécharge un exécutable code et peut l'installer avec très peu d'interaction utilisateur. Cela fait du chemin de mise à jour une frontière de sécurité, et non une simple fonctionnalité de confort. La documentation officielle d'Electron décrit des contraintes de plateforme comme macOS ATS, et des analyses de sécurité ont documenté un scénario en 2022 où des attaquants contrôlant l'infrastructure de mise à jour pouvaient diffuser des packages malveillants passant malgré tout les contrôles de signature code, comme évoqué dans la documentation sur la sécurité de l'auto-update d'Electron Builder.

La signature Code reste fondamentale, mais elle ne constitue pas l’ensemble du modèle de confiance. Signez chaque release, vérifiez le certificat et l’identité pendant le CI, et maintenez une procédure de rotation des clés documentée. Sur macOS, associez la signature à la notarisation et au hardened runtime adapté à votre application. Sur Windows, assurez-vous que la propriété du certificat, son renouvellement et l’accès au build sont auditable. Linux nécessite une stratégie spécifique à la distribution, car Electron n’y fournit pas de mécanisme de mise à jour universel intégré.

Protéger les métadonnées avec autant de soin que le binaire

Un binaire signé peut toujours être associé à la mauvaise release si le canal de métadonnées est compromis ou mal configuré. Pensez à ajouter une signature de manifeste vérifiée contre une clé publique intégrée à l’application, à imposer une version minimale autorisée et à rejeter les downgrades inattendus, sauf si un chemin de récupération autorisé les permet explicitement.

Le feed mérite aussi des contrôles de production :

• Restreindre l’accès à la publication : Donner à la CI uniquement les permissions nécessaires pour publier les assets de release.
• Protéger les secrets de signature : Gardez les certificats et clés privées dans un stockage de secrets géré, pas dans les fichiers du dépôt.
• Épingler les dépendances : Verrouiller Electron, electron-builder et les dépendances transitives dans la CI.
• Revoir les artefacts : Analyser les packages générés et les comparer au commit et à la version prévus.
• Exiger un transport sécurisé : Respectez les exigences ATS et HTTPS strictes pour les requêtes de mise à jour.
• Surveiller les échecs de vérification : Considérez les échecs répétés de signature ou de manifeste comme des événements de sécurité, et non comme du simple bruit réseau.

L'écosystème d'outils maintenu d'Electron continue d'étendre la couverture du packaging et de l'updater, mais la maintenance ne dispense pas de la modélisation des menaces. L'objectif pratique est de garantir qu'un attaquant qui compromet un bucket, un CDN ou une étape de build ne puisse toujours pas forcer le client à accepter une release non autorisée. Les directives de vérification de signature fournissent un contexte utile pour concevoir cette couche de vérification supplémentaire.

Guide et checklist de mise à jour en production

Une release n'est prête que lorsqu'un autre ingénieur peut l'exploiter sous pression. Gardez la checklist à proximité du job de déploiement et du canal d'incident.

Points de contrôl’avant release

• Identité de la version : Confirmez que la version du package, le tag de la release, le SHA du commit et le changelog concordent.
• Signature : Vérifiez que chaque artefact de plateforme est signé et que la notarisation ou une validation équivalente est terminée.
• Contrat du manifeste : Confirmer latest.yml, latest-mac.yml, les hashes, les chemins et les blockmaps correspondent aux artefacts envoyés.
• Sécurité du canal : Publiez sur le flux interne ou beta avant de promouvoir le canal de release.
• Télémétrie : Confirm update checks, download progress, install completion, launch health, and errors are arriving.

Canary et déploiement complet

• Contrôle de cohorte : Commencez par un public interne ou bêta volontairement restreint.
• Budget de santé : Suspendre la promotion en cas de dépassement des seuils approuvés par l’équipe : échecs de lancement, d’upload de la mise à jour, d’exceptions du renderer ou d’authentification.
• Validation de la promotion : Exigez une décision explicite go/no-go avant de passer la release au flux stable.
• Impact client : Préparez la communication support avant une diffusion large, pas après le premier incident.

Réponse aux incidents

Si le nouveau binaire ne se lance pas, si la création de processus échoue ou si les téléchargements de mise à jour ne se terminent plus, arrêtez la promotion immédiatement. Restaurez le manifeste signé précédent, invalidez le marqueur de staging et vérifiez que les nouveaux clients pointent vers la version précédente. Confirmez ensuite via la télémétrie que le parc se rétablit avant d’annoncer la clôture.

Les commandes exactes de rollback dépendent de votre fournisseur, mais la séquence doit toujours être documentée : basculer le manifeste du canal vers la version précédente, invalider le tag de staging, pousser un marqueur de mise à jour forcée si le rétablissement l’exige, et vérifier le chemin de downgrade avec la télémétrie en direct. Un rollback non testé n’est qu’un espoir.

Capgo propose un updater pour Electron permettant de livrer des changements signés sur la couche web, avec des canaux ciblés, des contrôles de déploiement progressif et une observabilité des mises à jour, sans avoir à recompiler le shell natif à chaque modification du renderer. Si vous souhaitez séparer les releases de binaires natifs de la livraison contrôlée du JavaScript et du CSS, visitez Capgo et évaluez-l’en parallèle de votre pipeline de release Electron actuel.