docs/content/actions/using-workflows/triggering-a-workflow.md

title, shortTitle, intro, versions, type, topics, miniTocMaxHeadingLevel

title	shortTitle	intro	versions	type	topics	miniTocMaxHeadingLevel
Triggering a workflow	Triggering a workflow	How to automatically trigger {% data variables.product.prodname_actions %} workflows	fpt ghes ghae ghec * * * *	tutorial	Workflows CI CD	3

{% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-github-hosted-runners %}

About workflow triggers

Workflow triggers are events that cause a workflow to run. These events can be:

• Events that occur in your workflow's repository
• Events that occur outside of {% data variables.product.product_name %} and trigger a repository_dispatch event on {% data variables.product.product_name %}
• Scheduled times
• Manual

For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened.

Workflow triggers are defined with the on key. For more information, see "Workflow syntax for {% data variables.product.prodname_actions %}."

The following steps occur to trigger a workflow run:

1. An event occurs on your repository. The event has an associated commit SHA and Git ref.
2. {% data variables.product.product_name %} searches the .github/workflows directory in your repository for workflow files that are present in the associated commit SHA or Git ref of the event.
3. A workflow run is triggered for any workflows that have on: values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run.

Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, {% data variables.product.product_name %} sets the GITHUB_SHA (commit SHA) and GITHUB_REF (Git ref) environment variables in the runner environment. For more information, see "Using environment variables."

Triggering a workflow from a workflow

{% data reusables.github-actions.actions-do-not-trigger-workflows %} For more information, see "Authenticating with the GITHUB_TOKEN."

If you do want to trigger a workflow from within a workflow run, you can use a personal access token instead of GITHUB_TOKEN to trigger events that require a token. You'll need to create a personal access token and store it as a secret. To minimize your {% data variables.product.prodname_actions %} usage costs, ensure that you don't create recursive or unintended workflow runs. For more information about creating a personal access token, see "Creating a personal access token." For more information about storing a personal access token as a secret, see "Creating and storing encrypted secrets."

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 {% data variables.product.prodname_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:
          GITHUB_TOKEN: {% raw %}${{ secrets.MY_TOKEN }}{% endraw %}
          ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %}
        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:
          GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
          ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %}
        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

{% data reusables.github-actions.on-single-example %}

Using multiple events

{% data reusables.github-actions.on-multiple-example %}

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. {% data reusables.github-actions.actions-multiple-types %}

Using event activity types

{% data reusables.github-actions.actions-activity-types %}

Using filters

{% data reusables.github-actions.actions-filters %}

Using filters to target specific branches for pull request events

{% data reusables.actions.workflows.section-triggering-a-workflow-branches %}

Using filters to target specific branches or tags for push events

{% data reusables.actions.workflows.section-run-on-specific-branches-or-tags %}

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

{% data reusables.actions.workflows.section-triggering-a-workflow-paths %}

Using filters to target specific branches for workflow run events

{% data reusables.actions.workflows.section-specifying-branches %}

Defining inputs for manually triggered workflows

{% data reusables.github-actions.workflow-dispatch-inputs %}

{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %}

Defining inputs, outputs, and secrets for reusable workflows

{% data reusables.actions.reusable-workflows-ghes-beta %}

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 "Reusing workflows."

{% endif %}

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 "Webhook events and payloads."

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: {% raw %}${{ toJSON(github.event) }}{% endraw %}
        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 {% data variables.product.prodname_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:
          GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
          PR: {% raw %}${{ github.event.pull_request.html_url }}{% endraw %}
        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." For more information about event payloads, see "Webhook events and payloads."

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{% ifversion fpt or ghae or ghes > 3.1 or ghec %} and environments{% endif %} 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. 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'

For more information, see "Expressions."

{% ifversion fpt or ghae or ghes > 3.1 or ghec %}

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 "Using 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
        echo 'building'

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

{% note %}

{% data reusables.gated-features.environments %}

{% endnote %} {% endif %}

Available events

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