Déclencheurs GitHub Actions : événements et filtres

Un workflow ne sert à rien s'il ne se déclenche pas au bon moment. La clé on définit les événements qui lancent un workflow : un push, une pull request, une heure planifiée, un clic manuel. Bien la régler évite les exécutions inutiles — et les exécutions manquantes.

Ce que vous allez apprendre

Déclencher un workflow sur push et pull_request
Filtrer les exécutions par branche, tag et chemin de fichier
Planifier un workflow avec schedule et la syntaxe cron
Lancer un workflow à la main avec workflow_dispatch et ses inputs
Enchaîner des workflows avec workflow_run
Combiner plusieurs déclencheurs dans un même fichier

La clé `on` : qu'est-ce qui lance un workflow

Chaque fichier de workflow commence par une clé on qui liste les événements déclencheurs. GitHub surveille le dépôt en permanence : dès qu'un événement listé survient, il crée une exécution du workflow. Sans on, le workflow ne se déclenche jamais.

Un workflow peut écouter un seul événement ou plusieurs à la fois — chacun avec ses propres filtres.

push et pull_request : les déclencheurs du quotidien

push et pull_request couvrent l'immense majorité des besoins de CI : valider le code à chaque envoi et à chaque proposition de fusion.

Réagir aux push

L'événement push déclenche le workflow quand des commits arrivent sur le dépôt. Le filtre branches restreint aux branches qui vous intéressent :

on:
  push:
    branches:
      - main

Sans filtre branches, le workflow se lance sur toutes les branches — y compris les branches de travail éphémères, ce qui consomme des minutes inutilement.

Réagir aux pull requests

L'événement pull_request déclenche le workflow sur les pull requests visant votre dépôt. Le filtre types précise quelles activités comptent :

on:
  pull_request:
    types: [opened, synchronize, reopened]

Par défaut, pull_request réagit déjà à opened, synchronize et reopened — inutile de les répéter sauf pour en ajouter ou en retirer. Les types les plus utiles au-delà du défaut sont labeled, closed et ready_for_review.

Filtrer : branches, tags et chemins

Les filtres évitent les exécutions inutiles. Trois axes existent : la branche, le tag et le chemin de fichier modifié.

on:
  push:
    branches:
      - main
      - 'release/**'
    paths:
      - 'src/**'
      - 'package.json'

Le filtre paths est précieux : il ne lance le workflow que si un fichier pertinent a changé. Inutile de relancer la CI complète pour une faute de frappe dans un fichier Markdown. La forme inverse, paths-ignore, exclut au lieu d'inclure :

on:
  push:
    paths-ignore:
      - 'docs/**'
      - '**.md'

Pour réagir à la publication d'une version, filtrez sur les tags :

on:
  push:
    tags:
      - 'v*'

schedule : exécuter un workflow périodiquement

L'événement schedule déclenche un workflow à intervalle régulier, via une expression cron. C'est l'outil des tâches récurrentes : audit de sécurité nocturne, nettoyage, rapport hebdomadaire.

on:
  schedule:
    - cron: '0 6 * * 1'   # Chaque lundi à 6h00 UTC

Les cinq champs cron sont : minute, heure, jour du mois, mois, jour de la semaine. Deux pièges reviennent souvent :

L'heure est toujours en UTC — pas votre fuseau local.
Un workflow planifié ne tourne que depuis la branche par défaut du dépôt.

GitHub n'exécute pas les schedule à la seconde près : en période de charge, le déclenchement peut glisser de plusieurs minutes.

workflow_dispatch : le déclenchement manuel

L'événement workflow_dispatch ajoute un bouton « Run workflow » dans l'onglet Actions. C'est le déclencheur des opérations volontaires : déploiement, restauration, génération à la demande.

Il accepte des inputs — des paramètres que l'opérateur saisit au lancement :

name: Déploiement manuel

on:
  workflow_dispatch:
    inputs:
      environnement:
        description: 'Environnement cible'
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version à déployer (tag)'
        required: true
        type: string

permissions: {}

jobs:
  deploy:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Récupérer le code
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      - name: Déployer
        env:
          ENVIRONNEMENT: ${{ inputs.environnement }}
          VERSION: ${{ inputs.version }}
        run: ./deploy.sh "$ENVIRONNEMENT" "$VERSION"

Le type: choice impose une liste fermée de valeurs — l'opérateur ne peut pas se tromper. Les inputs se lisent via le contexte inputs, transmis ici par un bloc env: : interpoler ${{ }} directement dans un run: ouvrirait une injection de commande.

workflow_run : enchaîner des workflows

L'événement workflow_run déclenche un workflow après la fin d'un autre. Il sert à séparer les responsabilités — par exemple, un workflow de build, puis un workflow de déploiement qui ne consomme que l'artefact produit.

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches: [main]

Le champ workflows référence l'autre workflow par son name, pas par son nom de fichier. Le workflow déclenché s'exécute toujours depuis la branche par défaut, et accède au résultat du premier via le contexte github.event.workflow_run.

Ce découplage est aussi un patron de sécurité : il permet de traiter du code non fiable dans un premier workflow sans secrets, puis de déployer dans un second. Le détail est couvert dans Sécuriser pull_request_target.

pull_request_target : le déclencheur à manier avec précaution

L'événement pull_request_target ressemble à pull_request, mais il s'exécute dans le contexte du dépôt cible, avec accès aux secrets — même pour une pull request venue d'un fork.

Tant que vous débutez, restez sur pull_request : il est sûr par défaut puisqu'il n'expose pas les secrets aux forks.

Combiner plusieurs déclencheurs

Un même workflow peut écouter plusieurs événements. C'est fréquent pour un pipeline de CI qui doit tourner sur les pushes, les pull requests, et aussi à la demande :

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 6 * * 1'
  workflow_dispatch:

À l'intérieur du workflow, le contexte github.event_name indique quel événement a déclenché l'exécution. C'est utile pour adapter le comportement — un sujet traité dans Conditions et if.

À retenir

La clé on définit les événements qui lancent un workflow — sans elle, rien ne se déclenche.
push et pull_request couvrent la CI du quotidien ; filtrez push par branches pour éviter les exécutions inutiles.
Les filtres paths, branches et tags ciblent les exécutions ; on ne mélange jamais une forme et son inverse (paths / paths-ignore).
schedule planifie en cron UTC, et uniquement depuis la branche par défaut.
workflow_dispatch ajoute un déclenchement manuel avec des inputs typés (choice, string, boolean).
workflow_run enchaîne les workflows ; pull_request_target est puissant mais dangereux — à n'utiliser qu'en connaissance de cause.

Prochaines étapes

Conditions et if Adapter le comportement selon l'événement déclencheur

Contexts et expressions Lire github.event_name, inputs et les autres contextes

Workflows réutilisables Le déclencheur workflow_call pour factoriser vos pipelines

Sécuriser pull_request_target Comprendre et neutraliser le déclencheur le plus à risque

Pour la liste exhaustive des événements, consultez la documentation officielle sur les déclencheurs.