Triggering a workflow

Prerequisites

To learn more about workflows and triggering workflows, see Workflows.

Triggering a workflow from a workflow

Lorsque vous utilisez le GITHUB_TOKEN du référentiel pour effectuer des tâches, les événements déclenchés par le GITHUB_TOKEN, à l’exception du workflow_dispatch et du repository_dispatch, ne créeront pas une nouvelle exécution du flux de travail. Cela vous empêche de créer accidentellement des exécutions de workflow récursives. Par exemple, si une exécution de workflow pousse (push) du code à l’aide du GITHUB_TOKEN du dépôt, aucun nouveau workflow ne s’exécute même quand le dépôt contient un workflow configuré pour s’exécuter quand des événements push se produisent. For more information, see Use GITHUB_TOKEN for authentication in workflows.

If you do want to trigger a workflow from within a workflow run, you can use a GitHub App installation access token or a personal access token instead of GITHUB_TOKEN to trigger events that require a token.

If you use a GitHub App, you'll need to create a GitHub App and store the app ID and private key as secrets. For more information, see Effectuer des requêtes d’API authentifiées avec une application GitHub dans un workflow GitHub Actions. If you use a personal access token, you'll need to create a personal access token and store it as a secret. For more information about creating a personal access token, see Gestion de vos jetons d'accès personnels. For more information about storing secrets, see Using secrets in GitHub Actions.

To minimize your GitHub Actions usage costs, ensure that you don't create recursive or unintended workflow runs.

For example, the following workflow uses a personal access token (stored as a secret called MY_TOKEN) to add a label to an issue via GitHub CLI. Any workflows that run when a label is added will run once this step is performed.

on:
  issues:
    types:
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.MY_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit $ISSUE_URL --add-label "triage"

Conversely, the following workflow uses GITHUB_TOKEN to add a label to an issue. It will not trigger any workflows that run when a label is added.

on:
  issues:
    types:
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit $ISSUE_URL --add-label "triage"

Using events to trigger workflows

Use the on key to specify what events trigger your workflow. For more information about events you can use, see Events that trigger workflows.

Using a single event

Par exemple, un workflow avec la valeur on suivante s’exécute quand une poussée (push) est effectuée dans une branche incluse dans son dépôt :

on: push

Using multiple events

Vous pouvez spécifier un événement unique ou plusieurs événements. Par exemple, un workflow avec la valeur on suivante s’exécute quand une poussée (push) est effectuée dans une branche du dépôt ou quand quelqu’un duplique (fork) le dépôt :

on: [push, fork]

Si vous spécifiez plusieurs événements, un seul de ces événements a besoin de se produire pour déclencher votre workflow. Si plusieurs événements déclencheurs se produisent pour votre workflow en même temps, plusieurs exécutions de workflow sont déclenchées.

Using activity types and filters with multiple events

You can use activity types and filters to further control when your workflow will run. For more information, see Using event activity types and Using filters. Si vous spécifiez des types d’activités ou des filtres pour un événement et que votre workflow se déclenche sur plusieurs événements, vous devez configurer chaque événement séparément. Vous devez ajouter un signe deux-points (:) à tous les événements, notamment aux événements sans configuration.

Par exemple, un workflow avec la valeur on suivante s’exécute quand :

• Une étiquette est créée.
• Une poussée (push) est effectuée dans la branche main du dépôt.
• Une poussée (push) est effectuée dans une branche compatible avec GitHub Pages.

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

Using event activity types

Certains événements ont des types d’activités qui vous donnent davantage de contrôle sur le moment où votre workflow devrait s’exécuter. Utilisez on.<event_name>.types pour définir le type d’activité d’événement qui déclenchera l’exécution d’un workflow.

Par exemple, l’événement issue_comment a les types d’activité created, edited et deleted. Si votre worflow se déclenche sur l’événement label, il s’exécute chaque fois qu’une étiquette est créée, modifiée ou supprimée. Si vous spécifiez le type d’activité created de l’événement label, votre workflow s’exécute quand une étiquette est créée, mais pas quand une étiquette est modifiée ou supprimée.

on:
  label:
    types:
      - created

Si vous spécifiez plusieurs types d’activités, un seul de ceux-ci doit se produire pour déclencher votre workflow. Si plusieurs types d’activité d’événement déclencheur pour votre workflow se produisent simultanément, plusieurs exécutions de workflow seront déclenchées. Par exemple, le workflow suivant se déclenche quand un problème est ouvert ou étiqueté. Si un problème avec deux étiquettes est ouvert, trois exécutions de workflow démarrent : une pour l’événement d’ouverture du problème, et deux pour les deux événements étiquetés du problème.

on:
  issues:
    types:
      - opened
      - labeled

Pour plus d’informations sur chaque événement et leurs types d’activité, consultez Events that trigger workflows.

Using filters

Certains événements comportent des filtres qui vous permettent de mieux contrôler le moment où votre workflow devrait s’exécuter.

Par exemple, l’événement push comporte un filtre branches avec lequel votre workflow ne s’exécute que lorsqu’un envoi (push) vers une branche qui correspond au filtre branches se produit, et non lorsque n’importe quel envoi se produit.

on:
  push:
    branches:
      - main
      - 'releases/**'

Using filters to target specific branches for pull request events

Quand vous utilisez les événements pull_request et pull_request_target vous pouvez configurer un workflow afin qu’il s’exécute uniquement pour les demandes de tirage (pull requests) qui ciblent des branches spécifiques.

Utilisez le filtre branches quand vous souhaitez inclure des modèles de noms de branches, ou quand vous souhaitez à la fois inclure et exclure des modèles de noms de branches. Utilisez le filtre branches-ignore quand vous souhaitez exclure uniquement les modèles de nom de branche. Vous ne pouvez pas utiliser les filtres branches et branches-ignore en même temps pour le même événement dans un workflow.

Si vous définissez à la fois branches/branches-ignore et paths/paths-ignore, le workflow s’exécute uniquement quand les deux filtres sont satisfaits.

Les mots clés branches et branches-ignore acceptent les modèles Glob qui utilisent des caractères tels que *, **, +, ?, ! et certains autres pour correspondre à plusieurs noms de branches. Si un nom contient l’un de ces caractères et si vous souhaitez une correspondance littérale, vous devez utiliser le caractère d’échappement \ avec chacun de ces caractères spéciaux. Pour plus d’informations sur les modèles glob, consultez l’Workflow syntax for GitHub Actions.

Example: Including branches

Les modèles définis dans branches sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécute chaque fois qu’il existe un événement pull_request pour une demande de tirage qui cible :

• Une branche nommée main (refs/heads/main)
• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom commence par releases/, par exemple releases/10 (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'

Vous ne devez pas utiliser le filtrage de chemin d’accès ou de branche pour ignorer les exécutions de workflow si celui-ci doit aboutir avant la fusion. Pour plus d’informations, consultez « Skipping workflow runs » et « Règles disponibles pour les ensembles de règles ».

Si un workflow est ignoré en raison du filtrage de branche, du filtrage de chemin d’accès ou d’un message de commit, les vérifications associées à ce workflow restent alors à l’état « En attente ». La fusion d’une demande de tirage (pull request) nécessitant la réussite de ces vérifications sera bloquée.

Example: Excluding branches

Quand un modèle correspond au modèle branches-ignore, le workflow ne s’exécute pas. Les modèles définis dans branches-ignore sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécute chaque fois qu’il existe un événement pull_request, sauf si la demande de tirage cible :

• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom correspond à releases/**-alpha, par exemple releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'

Example: Including and excluding branches

Vous ne pouvez pas utiliser branches et branches-ignore pour filtrer le même événement dans un seul workflow. Si vous souhaitez à la fois inclure et exclure des modèles de branche pour un seul événement, utilisez le filtre branches avec le caractère ! pour indiquer les branches à exclure.

Si vous définissez une branche avec le caractère !, vous devez également définir au moins une branche sans le caractère !. Si vous souhaitez uniquement exclure des branches, utilisez branches-ignore à la place.

L’ordre dans lequel vous définissez les modèles est important.

• Un modèle de correspondance négative (préfixé avec !) après une correspondance positive exclut la référence Git.
• Un modèle de correspondance positive après une correspondance négative inclut à nouveau la référence Git.

Le workflow suivant s’exécute sur les événements pull_request pour les demandes de tirage qui ciblent releases/10 ou releases/beta/mona, mais pas pour les demandes de tirage qui ciblent releases/10-alpha ou releases/beta/3-alpha, car le modèle négatif !releases/**-alpha suit le modèle positif.

on:
  pull_request:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

Using filters to target specific branches or tags for push events

Lorsque vous utilisez l’événement push, vous pouvez configurer un workflow pour qu’il s’exécute sur des branches ou des étiquettes spécifiques.

Utilisez le filtre branches lorsque vous souhaitez inclure des modèles de noms de branche ou lorsque vous souhaitez inclure et exclure des modèles de noms de branche. Utilisez le filtre branches-ignore quand vous souhaitez exclure uniquement les modèles de nom de branche. Vous ne pouvez pas utiliser les filtres branches et branches-ignore en même temps pour le même événement dans un workflow.

Utilisez le filtre tags lorsque vous souhaitez inclure des modèles de nom d’étiquette ou lorsque vous souhaitez inclure et exclure des modèles de noms d’étiquette. Utilisez le filtre tags-ignore lorsque vous souhaitez exclure uniquement les modèles de nom d’étiquette. Vous ne pouvez pas utiliser les filtres tags et tags-ignore en même temps pour le même événement dans un workflow.

Si vous définissez uniquement tags/tags-ignore ou uniquement branches/branches-ignore, le flux de travail ne s’exécutera pas pour les événements affectant la référence Git non définie. Si vous définissez ni tags/tags-ignore ou branches/branches-ignore, le flux de travail sera exécuté pour les événements affectant les branches ou les étiquettes. Si vous définissez à la fois branches/branches-ignore et paths/paths-ignore, le workflow s’exécute uniquement quand les deux filtres sont satisfaits.

Les mots clés branches, branches-ignore, tags et tags-ignore acceptent des modèles Glob qui utilisent des caractères tels que *, **, +, ?, ! et d’autres pour correspondre à plus d’un nom de branche ou d’étiquette Si un nom contient l’un de ces caractères et que vous souhaitez une correspondance littérale, vous devez échapper chacun de ces caractères spéciaux avec \. Pour plus d’informations sur les modèles glob, consultez l’Workflow syntax for GitHub Actions.

Example: Including branches and tags

Les modèles définis dans branches et tags sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécuterait chaque fois qu’il existe un événement push pour :

• Une branche nommée main (refs/heads/main)
• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom commence par releases/, par exemple releases/10 (refs/heads/releases/10)
• Une étiquette nommée v2 (refs/tags/v2)
• Une étiquette dont le nom commence par v1., comme v1.9.1 (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:
      - v2
      - v1.*

Example: Excluding branches and tags

Lorsqu’un modèle correspond au modèle branches-ignore ou tags-ignore, le workflow n’est pas exécuté. Les modèles définis dans branches et tags sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécuterait chaque fois qu’il existe un événement push, sauf si l’événement push concerne :

• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom correspond à releases/**-alpha, par exemple releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)
• Une étiquette nommée v2 (refs/tags/v2)
• Une étiquette dont le nom commence par v1., comme v1.9 (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v2
      - v1.*

Example: Including and excluding branches and tags

Vous ne pouvez pas utiliser branches et branches-ignore pour filtrer le même événement dans un même workflow. De même, vous ne pouvez pas utiliser tags et tags-ignore pour filtrer le même événement dans un même workflow. Si vous souhaitez inclure et exclure des modèles de branche ou d’étiquette pour un seul événement, utilisez le filtre branches ou tags avec le caractère ! pour indiquer quelles branches ou étiquettes doivent être exclues.

Si vous définissez une branche avec le caractère !, vous devez également définir au moins une branche sans caractère !. Si vous souhaitez uniquement exclure des branches, utilisez branches-ignore à la place. De même, si vous définissez une étiquette avec le caractère !, vous devez également définir au moins une étiquette sans caractère !. Si vous souhaitez uniquement exclure des étiquettes, utilisez tags-ignore à la place.

L’ordre dans lequel vous définissez les modèles est important.

• Un modèle de correspondance négative (préfixé avec !) après une correspondance positive exclut la référence Git.
• Un modèle de correspondance positive après une correspondance négative inclut à nouveau la référence Git.

Le workflow suivant s’exécute sur les envois push vers releases/10 ou releases/beta/mona, mais pas sur releases/10-alpha ou releases/beta/3-alpha parce que le modèle négatif !releases/**-alpha fait suite au modèle positif.

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

Using filters to target specific paths for pull request or push events

Lorsque vous utilisez les événements push et pull_request événements, vous pouvez configurer un workflow pour qu’il s’exécute en fonction des chemins d’accès aux fichiers qui ont changé. Les filtres de chemin d’accès ne sont pas évalués pour les envois (push) d’étiquettes.

Utilisez le filtre paths lorsque vous souhaitez inclure des modèles de chemins d’accès aux fichiers, ou lorsque vous souhaitez à la fois inclure et exclure des modèles de modèles de chemins d’accès aux fichiers. Utilisez le filtre paths-ignore lorsque vous souhaitez uniquement exclure modèles de chemins d’accès aux fichiers. Vous ne pouvez pas utiliser les filtres paths et paths-ignore en même temps pour le même événement dans un workflow. Si vous souhaitez inclure et exclure des modèles de chemin d’accès pour un seul événement, utilisez le filtre paths avec en préfixe le caractère ! pour indiquer les chemins d’accès à exclure.

Si vous définissez à la fois branches/branches-ignore et paths/paths-ignore, le workflow s’exécute uniquement quand les deux filtres sont satisfaits.

Les mots clés paths et paths-ignore acceptent des modèles globaux qui utilisent les caractères génériques * et ** pour faire correspondre plusieurs noms de chemin d’accès. Pour plus d’informations, consultez Workflow syntax for GitHub Actions.

Example: Including paths

Si au moins un chemin d’accès correspond à un modèle dans le filtre paths, le workflow s’exécute. Par exemple, le workflow suivant s’exécuterait chaque fois que vous envoyez (push) un fichier JavaScript (.js).

on:
  push:
    paths:
      - '**.js'

Vous ne devez pas utiliser le filtrage de chemin d’accès ou de branche pour ignorer les exécutions de workflow si celui-ci doit aboutir avant la fusion. Pour plus d’informations, consultez « Skipping workflow runs » et « Règles disponibles pour les ensembles de règles ».

Si un workflow est ignoré en raison du filtrage de chemin d’accès, du filtrage de branche ou d’un message de commit, les vérifications associées à ce workflow restent alors à l’état « En attente ». La fusion d’une demande de tirage (pull request) nécessitant la réussite de ces vérifications sera bloquée.

Example: Excluding paths

Lorsque tous les noms de chemin d’accès correspondent à des modèles dans paths-ignore, le workflow ne s’exécute pas. Si des noms de chemin d’accès ne correspondent pas à des modèles dans paths-ignore, même si certains noms de chemin d’accès correspondent aux modèles, le workflow s’exécute.

Un workflow avec le filtre de chemin d’accès suivant s’exécute uniquement sur des événements push qui incluent au moins un fichier en dehors du répertoire docs à la racine du dépôt.

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

Example: Including and excluding paths

Vous ne pouvez pas utiliser paths et paths-ignore pour filtrer le même événement dans un seul workflow. Si vous souhaitez inclure et exclure des modèles de chemin d’accès pour un seul événement, utilisez le filtre paths avec en préfixe le caractère ! pour indiquer les chemins d’accès à exclure.

Si vous définissez un chemin d’accès avec le caractère !, vous devez également définir au moins un chemin d’accès sans caractère !. Si vous souhaitez uniquement exclure des chemins d’accès, utilisez plutôt paths-ignore.

L’ordre dans lequel vous définissez les modèles paths est important :

• Un modèle négatif de correspondance (préfixé avec !) après une correspondance positive exclut le chemin d’accès.
• Un modèle positif de correspondance après une correspondance négative inclut à nouveau le chemin d’accès.

Cet exemple s’exécute à chaque fois que l’événement push inclut un fichier dans le répertoire sub-project ou ses sous-répertoires, sauf si le fichier se trouve dans le répertoire sub-project/docs. Par exemple, un envoi (push) qui change sub-project/index.js ou sub-project/src/index.js déclenche l’exécution d’un workflow, au contraire d’un envoi (push) changeant uniquement sub-project/docs/readme.md.

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git diff comparisons

Le filtre détermine si un workflow doit s’exécuter en évaluant les fichiers modifiés et en les exécutant sur la liste paths-ignore ou paths. S’il n’y a pas de fichier modifié, le workflow ne s’exécute pas.

GitHub génère la liste des fichiers modifiés à l’aide de différences de deux points pour les envois (push) et de différences de trois points pour les demandes de tirage :

• Demandes de tirage : les différences de trois points sont une comparaison entre la version la plus récente de la branche de rubrique, et la validation dans laquelle la branche de rubrique a été synchronisée pour la dernière fois avec la branche de base.
• Envois (push) à des branches existantes : une différence de deux points compare directement les SHA principal et de base.
• Envois (push) à nouvelles branches : une différence de deux points par rapport au parent de l’élément ancêtre de la validation la plus profonde envoyées (push).

Pour plus d’informations, consultez « À propos de la comparaison des branches dans les demandes de tirage ».

Using filters to target specific branches for workflow run events

Lorsque vous utilisez l’événement workflow_run, vous pouvez spécifier les branches sur lesquelles le workflow déclencheur doit s’exécuter afin de déclencher votre workflow.

Les filtres branches et branches-ignore acceptent les modèles Glob qui utilisent des caractères tels que *, **, +, ?, ! et certains autres pour correspondre à plusieurs noms de branches. Si un nom contient l’un de ces caractères et que vous souhaitez une correspondance littérale, vous devez échapper chacun de ces caractères spéciaux avec \. Pour plus d’informations sur les modèles glob, consultez l’Workflow syntax for GitHub Actions.

Par exemple, un workflow avec le déclencheur suivant s’exécute uniquement lorsque le workflow nommé Build s’exécute sur une branche dont le nom commence par releases/ :

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

Un workflow avec le déclencheur suivant s’exécute uniquement lorsque le workflow nommé Build s’exécute sur une branche qui n’est pas nommée canary :

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

Vous ne pouvez pas utiliser les filtres branches et branches-ignore en même temps pour le même événement dans un workflow. Si vous souhaitez à la fois inclure et exclure des modèles de branche pour un seul événement, utilisez le filtre branches avec le caractère ! pour indiquer les branches à exclure.

L’ordre dans lequel vous définissez les modèles est important.

• Un modèle négatif de correspondance (préfixé avec !) après une correspondance positive exclut la branche.
• Un modèle positif de correspondance après une correspondance négative inclut à nouveau la branche.

Par exemple, un workflow avec le déclencheur suivant s’exécute lorsque le workflow nommé Build s’exécute sur une branche nommée releases/10 ou releases/beta/mona, mais pas releases/10-alpha, releases/beta/3-alpha ni main.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

Defining inputs for manually triggered workflows

Quand vous utilisez l’événement workflow_dispatch, vous pouvez éventuellement spécifier des entrées qui sont passées au workflow.

Ce déclencheur reçoit uniquement les événements lorsque le fichier de flux de travail se trouve sur la branche par défaut. Le workflow déclenché reçoit les entrées dans le contexte inputs. Pour plus d’informations, consultez Contextes.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if: ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

Defining inputs, outputs, and secrets for reusable workflows

You can define inputs and secrets that a reusable workflow should receive from a calling workflow. You can also specify outputs that a reusable workflow will make available to a calling workflow. For more information, see Reuse workflows.

Using event information

Information about the event that triggered a workflow run is available in the github.event context. The properties in the github.event context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label.

Viewing all properties of an event

Reference the webhook event documentation for common properties and example payloads. For more information, see Événements et charges utiles du webhook.

You can also print the entire github.event context to see what properties are available for the event that triggered your workflow:

jobs:
  print_context:
    runs-on: ubuntu-latest
    steps:
      - env:
          EVENT_CONTEXT: ${{ toJSON(github.event) }}
        run: |
          echo $EVENT_CONTEXT

Accessing and using event properties

You can use the github.event context in your workflow. For example, the following workflow runs when a pull request that changes package*.json, .github/CODEOWNERS, or .github/workflows/** is opened. If the pull request author (github.event.pull_request.user.login) is not octobot or dependabot[bot], then the workflow uses the GitHub CLI to label and comment on the pull request (github.event.pull_request.number).

on:
  pull_request:
    types:
      - opened
    paths:
      - '.github/workflows/**'
      - '.github/CODEOWNERS'
      - 'package*.json'

jobs:
  triage:
    if: >-
      github.event.pull_request.user.login != 'octobot' &&
      github.event.pull_request.user.login != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: "Comment about changes we can't accept"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ github.event.pull_request.html_url }}
        run: |
          gh pr edit $PR --add-label 'invalid'
          gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.'

For more information about contexts, see Contexts reference. For more information about event payloads, see Événements et charges utiles du webhook.

Further controlling how your workflow will run

If you want more granular control than events, event activity types, or event filters provide, you can use conditionals and environments to control whether individual jobs or steps in your workflow will run.

Using conditionals

You can use conditionals to further control whether jobs or steps in your workflow will run.

Example using a value in the event payload

For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on the issues labeled event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but the run_if_label_matches job will only execute if the label is named bug.

on:
  issues:
    types:
      - labeled

jobs:
  run_if_label_matches:
    if: github.event.label.name == 'bug'
    runs-on: ubuntu-latest
    steps:
      - run: echo 'The label was bug'

Example using event type

For example, if you want to run different jobs or steps depending on what event triggered the workflow, you can use a conditional to check whether a specific event type exists in the event context. The following workflow will run whenever an issue or pull request is closed. If the workflow ran because an issue was closed, the github.event context will contain a value for issue but not for pull_request. Therefore, the if_issue step will run but the if_pr step will not run. Conversely, if the workflow ran because a pull request was closed, the if_pr step will run but the if_issue step will not run.

on:
  issues:
    types:
      - closed
  pull_request:
    types:
      - closed

jobs:
  state_event_type:
    runs-on: ubuntu-latest
    steps:
    - name: if_issue
      if: github.event.issue
      run: |
        echo An issue was closed
    - name: if_pr
      if: github.event.pull_request
      run: |
        echo A pull request was closed

For more information about what information is available in the event context, see Using event information. For more information about how to use conditionals, see Evaluate expressions in workflows and actions.

Using environments to manually trigger workflow jobs

If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, see Managing environments for deployment. Then, reference the environment name in a job in your workflow using the environment: key. Any job referencing the environment will not run until at least one reviewer approves the job.

For example, the following workflow will run whenever there is a push to main. The build job will always run. The publish job will only run after the build job successfully completes (due to needs: [build]) and after all of the rules (including required reviewers) for the environment called production pass (due to environment: production).

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: build
        run: |
          echo 'building'

  publish:
    needs: [build]
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: publish
        run: |
          echo 'publishing'

Available events

For a full list of available events, see Events that trigger workflows.