on

Use on to define a trigger that runs the workflow. Triggers are events that start a workflow run.

There are five types of triggers.

push - Starts the workflow based upon a pull request. For more information, refer to:
- push usage examples
- Configure a push or pull_request trigger
pull_request - Starts the workflow based upon a push request and Git tags. For more information, refer to:
- pull_request usage examples
- Configure a push or pull_request trigger
schedule- Starts the workflow based upon configured cron schedules. For more information, refer to:
- schedule usage example
- Configure a schedule trigger

Use of inputs, secrets and outputs is supported with workflow_call and workflow_dispatch triggers.

workflow_dispatch - Enables users with permission to manually trigger workflow runs via the CloudBees platform UI or API. For details refer to:
workflow_call - Enables a workflow to be called to execute as a reusable workflow job. For more information, refer to:
- workflow_call example usage
- Reusable workflows for details.

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 /.

Push usage example

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/**'▼

Pull_request usage examples

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, 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▼

`schedule` usage examples

In the following example, a workflow runs in response to configured schedules. Scheduled triggers execute only on the default branch of the repository.

Cron expressions are configured in UTC timezone.

on:
 schedule:
    - cron: 0 7 1 * 1,2,3,4
    - cron: 0 14 * * 1,2,3,4
    - cron: 0 15 * * 1,2,3,4
    - cron: 0 16 * * 1,2,3,4▼

workflow_dispatch usage example

In the following example, a workflow runs in response to being manually triggered via the UI or API.

on:
 workflow_dispatch:
    inputs:
      stringIn:
        type: string
        default: String input value
        required: true
        description: Input string
      pickList:
        type: choice
        options:
          - abc
          - def
          - ghi
        default: abc
        description: Pick list description
      boole:
        type: boolean
        default: true
        description: A Boolean entry
      RetryCount:
        type: number
        default: 3
        required: true
        description: Retry deployment a certain number of times.▼

workflow_call usage example

In the following example, a workflow with this call trigger will run in response to call from a reusable workflow job.

on:
  workflow_call:
    inputs:
      config-path:
        required: false
        type: string
        default: ./config
        description: Path to config files for app
    secrets:
      access-token:
        required: true
        description: The token to use for deploying
    outputs:
      deploy-result:
        value: ${{ jobs.deploy-shared.outputs.result }}
        description: simple value output▼

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

on