Contrôler la simultanéité des workflows et des tâches

Utilisation de la concurrence dans différents scénarios

Vous pouvez utiliser jobs.<job_id>.concurrency pour vous assurer qu’un seul travail ou workflow utilisant le même groupe d’accès concurrentiel s’exécute à la fois. Un groupe d’accès concurrentiel peut être n’importe quelle chaîne ou expression. Contextes d’expression autorisés : github, inputs, vars, needs, strategy et matrix. Pour plus d’informations sur les expressions, consultez Évaluer des expressions dans les workflows et les actions..

Vous pouvez également spécifier concurrency au niveau du workflow. Pour plus d’informations, consultez concurrency.

Cela signifie qu’il peut y avoir au plus un travail en cours d’exécution ou un workflow dans un groupe de concurrence à tout moment. Quand un travail ou un workflow simultané est mis en file d’attente, si un autre travail ou workflow utilisant le même groupe d’accès concurrentiel dans le dépôt est en cours d’exécution, le travail ou le workflow en file d’attente a la valeur pending. Par défaut, tout travail ou flux de travail existant pending dans le même groupe de concurrence sera annulé et le nouveau travail ou flux de travail mis en file d'attente prendra sa place.

Pour annuler également un travail ou un workflow en cours d’exécution dans le même groupe d’accès concurrentiel, spécifiez cancel-in-progress: true. Pour annuler de façon conditionnelle les travaux ou les flux de travail en cours d’exécution dans le même groupe d’accès concurrentiel, vous pouvez spécifier cancel-in-progress en tant qu’expression avec l’un des contextes d’expression autorisés.

Pour autoriser plusieurs pending exécutions de travail ou de flux de travail à attendre dans le même groupe d’accès concurrentiel, utilisez la propriété facultative queue . La queue propriété accepte les valeurs suivantes :

• single (valeur par défaut) : Au plus un travail ou une exécution de flux de travail peut se trouver pending dans le groupe d’accès concurrentiel. Lorsqu’une nouvelle exécution de travail ou de flux de travail est mise en file d’attente, toute exécution de travail ou de flux de travail existante pending dans le même groupe est annulée et remplacée.
• max: jusqu’à 100 travaux ou exécutions de flux de travail peuvent être pending dans le groupe de concurrence. Lorsque la file d’attente est pleine, les travaux supplémentaires ou les exécutions de flux de travail sont annulées.

La combinaison de queue: max et de cancel-in-progress: true n'est pas autorisée et entraînera une erreur de validation du flux de travail.

Exemple : utilisation de la concurrence et du comportement par défaut

Le comportement par défaut consiste à autoriser l’exécution simultanée de GitHub Actions plusieurs travaux ou flux de travail. Le mot clé concurrency vous permet de contrôler la concurrence des exécutions de flux de travail.

Par exemple, vous pouvez utiliser le mot clé concurrency immédiatement après le lieu de définition des conditions de déclenchement afin de limiter la concurrence des exécutions de l'ensemble du flux de travail pour une branche spécifique :

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Vous pouvez également limiter la concurrence des projets au sein d'un flux de travail en utilisant le mot-clé concurrency au niveau du projet :

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

Exemple : groupes de concurrence

Les groupes de concurrence permettent de gérer et de limiter l'exécution des flux de travail ou des projets qui partagent la même clé de concurrence.

La clé concurrency est utilisée pour regrouper des flux de travail ou des projets ensemble dans un groupe de concurrence. Lorsque vous définissez une concurrency clé, GitHub Actions garantit qu’un seul flux de travail ou travail avec cette clé s’exécute à tout moment. Si une nouvelle exécution ou un travail commence avec la même concurrency clé, GitHub Actions annulera toute exécution ou travail déjà en cours avec cette clé. La clé concurrency peut être une chaîne codée en dur, ou il peut s'agir d'une expression dynamique qui inclut des variables de contexte.

Il est possible de définir des conditions de concurrence dans votre flux de travail afin que le flux de travail ou le projet fasse partie d'un groupe de concurrence.

En d'autres termes, lorsqu'un flux de travail ou un projet est lancé, GitHub annule tous les flux de travail ou projets déjà en cours dans le même groupe de concurrence. Cette fonction est utile dans les scénarios où vous souhaitez empêcher les exécutions parallèles pour un certain ensemble de flux de travail ou de projets, comme ceux utilisés pour les déploiements dans un environnement intermédiaire, afin d'éviter les actions susceptibles de provoquer des conflits ou de consommer plus de ressources qu'il n'est nécessaire.

Dans cet exemple, job-1 fait partie d'un groupe de concurrence nommé staging_environment. En d'autres termes, si une nouvelle exécution de job-1 est déclenchée, toutes les exécutions du même projet dans le groupe de concurrence staging_environment qui sont déjà en cours seront annulées.

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

Par ailleurs, l'utilisation d'une expression dynamique comme concurrency: ci-${{ github.ref }} dans votre flux de travail signifie que le flux de travail ou le projet fera partie d'un groupe de concurrence dont le nom ci- est suivi de la référence de la branche ou de la balise qui a déclenché le flux de travail. Dans cet exemple, si un nouveau commit est poussé vers la branche principale alors qu'une exécution précédente est toujours en cours, cette dernière sera annulée et la nouvelle commencera.

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Exemple : Mise en file d’attente de plusieurs exécutions en attente

Par défaut, une seule exécution de travail ou de flux de travail peut se trouver pending dans un groupe d’accès concurrentiel à la fois. Pour autoriser plusieurs exécutions à être ajoutées à la file d'attente plutôt que d'être annulées, définissez queue: max. Avec queue: max, jusqu’à 100 travaux ou exécutions de flux de travail peuvent attendre dans le groupe d’accès concurrentiel ; une fois la file d’attente remplie, toutes les exécutions supplémentaires sont annulées.

Par exemple, les déploiements de flux de travail suivants sont mis en file d’attente dans l’environnement production , en les traitant un à la fois en fonction du moment où chaque exécution a commencé à attendre le groupe d’accès concurrentiel :

on:
  push:
    branches:
      - main

concurrency:
  group: production-deploy
  queue: max

Notez que queue: max ne peut pas être combiné avec cancel-in-progress: true, car les deux options décrivent des comportements contradictoires pour la gestion des exécutions en cours.

Exemple : Utilisation de la concurrence pour annuler un travail ou une exécution en cours

Pour utiliser la concurrence pour annuler un travail ou une exécution en cours dans GitHub Actions, vous pouvez utiliser la clé concurrency avec l’option cancel-in-progress définie sur true.

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Remarquez que dans cet exemple, sans définir de groupe de concurrence particulier, GitHub Actions annulera toute exécution en cours de la tâche ou du flux de travail.

Exemple : Utilisation d’une valeur de secours

Si vous créez le nom de groupe avec une propriété définie uniquement pour des événements spécifiques, vous pouvez utiliser une valeur de secours. Par exemple, github.head_ref est défini uniquement pour les événements pull_request. Si votre workflow répond à d’autres événements en plus des événements pull_request, vous devez fournir une valeur de secours pour éviter une erreur de syntaxe. Le groupe d’accès concurrentiel suivant annule les travaux ou les exécutions en cours pour les événements pull_request uniquement. Si github.head_ref n’est pas défini, le groupe d’accès concurrent utilise l’ID d’exécution, qui offre la garantie d’être à la fois unique et défini pour l’exécution.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Exemple : Annuler uniquement les travaux ou les exécutions en cours pour le workflow actuel

Si vous avez plusieurs workflows dans le même dépôt, les noms de groupes de concurrence doivent être uniques entre les workflows pour éviter d'annuler des tâches ou des exécutions en cours provenant d'autres workflows. Sinon, tout travail en cours ou en attente est annulé, quel que soit le workflow.

Pour annuler uniquement les exécutions en cours du même workflow, vous pouvez utiliser la propriété github.workflow afin de créer le groupe d’accès concurrentiel :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Exemple : Annuler uniquement les travaux en cours sur des branches spécifiques

Si vous souhaitez annuler des travaux en cours sur certaines branches, mais pas sur d’autres, vous pouvez utiliser des expressions conditionnelles avec cancel-in-progress. Par exemple, vous pouvez procéder ainsi si vous souhaitez annuler les processus en cours sur les branches de développement, mais pas sur les branches de release.

Pour n’annuler que les exécutions en cours du même workflow lorsqu’il n’est pas exécuté sur une branche de publication, vous pouvez définir cancel-in-progress comme une expression similaire à la suivante :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

Dans cet exemple, plusieurs envois push vers une branche release/1.2.3 n’annulent pas les exécutions en cours. Les envois (push) vers une autre branche, par exemple main, annulent les exécutions en cours.

Monitoring de vos travaux en cours dans votre organisation ou votre entreprise

Pour identifier des contraintes liées à la concurrence ou la mise en file d’attente, vous pouvez vérifier le nombre de travaux actuellement traités sur les exécuteurs hébergés par GitHub dans votre organisation ou entreprise. Pour plus d’informations, consultez « Affichage de vos tâches actuelles ».