on

Use on to define a trigger that runs the workflow. push and pull_request are the two repository event triggers that cause a workflow to execute. With event triggers, you can restrict the workflow to run only for specific branches or tags. branches and tags can be used together with on in the same workflow definition.

You can also manually execute a workflow, with workflow_dispatch. For more information, refer to the workflow trigger documentation.

Wildcards

Use a wildcard to match one or more branch or tag name. The * wildcard matches any character, but does not match /. The ** matches any character, including /.

Example usages

In the following example, a workflow runs in response to a pull request event to the main branch of a repository, or it can be manually executed.

on:
  pull_request:
    branches:
      - 'main'
  workflow_dispatch:▼

In the following example, a workflow runs in response to a push event to either a repository demo branch or to any file in its test directory.

on:
  push:
    branches:
      - 'demo'
      - 'test/**'▼

In the following example, Git tags are used to specify the workflow execution. The workflow is defined to run in response to tags with distinct name patterns. Conditionals using the name patterns of the tags determine which job runs.

on:
  push:
    tags:
      - "v*"
      - "hotfix-*"

jobs:
  build:
    steps:
      - uses: Example/hello-world-action
        name: Greet
        with:
          who-to-greet: ${{ cloudbees.scm.ref }}

  deploy-release:
    if: ${{ startsWith(cloudbees.scm.ref, 'refs/tags/v') }}
    environment: dev
    steps:
      - uses: docker://golang:1.20
        name: Deploy if version tag
        run: echo "Pretending to deploy RELEASE to namespace ${{ vars.DEPLOY_NAMESPACE }} using
          token ${{ secrets.DEPLOY_TOKEN }}"
        shell: sh
    needs: build

  deploy-hotfix:
    if: ${{ startsWith(cloudbees.scm.ref, 'refs/tags/hotfix') }}
    environment: dev
    steps:
      - uses: docker://golang:1.20
        name: Deploy if hotfix tag
        run: echo "Pretending to deploy HOTFIX to namespace ${{ vars.DEPLOY_NAMESPACE }} using
          token ${{ secrets.DEPLOY_TOKEN }}"
        shell: sh
    needs: build▼

Definition of a triggering event

The table below defines when a push event results in a workflow run:

Table 1. Push events to a branch and resulting workflow
`on.push.branches` input	Push to repository branch	Workflow result
`'test/*'`	`'test/foo'`	Runs
`'test/*'`	`'test/foo/bar'`	Does not run
`'test/*/bar'`	`'test/foo/bar'`	Runs
`'test/**'`	`'test/foo'`	Runs
`'test/**'`	`'test/foo/bar'`	Runs
`'**'`	Any branch	Runs