Introduction

GitHub Actions is a powerful platform that enables developers to automate their software workflows by creating custom, event-driven pipelines. Triggering workflows is at the heart of GitHub Actions, allowing you to perform tasks automatically in response to various events. In this article, I will explore the different ways to trigger workflows in GitHub Actions, including events and triggers, scheduled workflows, and manual workflows.

Events and Triggers

Events and triggers form the foundation of GitHub Actions. Workflows are initiated by specific events that occur within a GitHub repository. These events can range from push and pull request events to repository and issue events, among others. By understanding how to leverage these events, you can create efficient and flexible workflows for your projects.

Push and Pull Request Events

Push and pull request events are among the most common triggers in GitHub Actions. When a commit is pushed to a repository or a pull request is created or updated, these events automatically trigger associated workflows.

• Push Event
  This event is triggered when a commit is pushed to a repository. You can configure the workflow to run only for specific branches or tags by using the branches or tags filters.

on:
  push:
    branches:
      - main
      - develop

• Pull Request Event
  This event is triggered when a pull request is created, synchronized (updated), or reopened. Similar to the push event, you can also specify the branches to run the workflow on using the branches filter.

on:
  pull_request:
    branches:
      - main

Repository and Issue Events

Repository and issue events provide more granular control over your workflows, allowing you to automate tasks based on specific changes in your repository.

• Repository Events
  Some examples of repository events include create, delete, fork, and star. These events are triggered when actions such as creating or deleting a branch, forking a repository, or starring a repository occur.

on:
  create:
    branches:
      - feature/*

• Issue Events
  Issue events are triggered when issues are created, edited, deleted, or have their state changed (e.g., opened or closed). You can use these events to automate tasks such as labeling or assigning issues.

on:
  issues:
    types:
      - opened
      - reopened

Other Events

There are numerous other events available in GitHub Actions, such as deployment, workflow_run, release, and check_run. These events offer additional options for triggering your workflows based on various repository activities.

on:
  release:
    types:
      - published

For a comprehensive list of available events and their descriptions, refer to the GitHub Actions documentation:

https://docs.github.com/en/actions/reference/events-that-trigger-workflows

Scheduled Workflows

Scheduled workflows allow you to run your GitHub Actions workflows at specific intervals, such as daily or weekly. This feature is particularly useful for tasks like automated testing, code analysis, and reporting.

Setting Up a Schedule

To set up a scheduled workflow, you need to use the schedule keyword in your workflow configuration file (.github/workflows/workflow.yml). The schedule keyword should be followed by a list of cron expressions that define when the workflow should run.

on:
  schedule:
    - cron: '0 0 * * *'

In this example, the workflow is scheduled to run every day at midnight (00:00).

Using Cron Syntax

Cron syntax is used to define the schedule for your workflow. A cron expression consists of five fields, representing minutes (0-59), hours (0-23), days of the month (1-31), months (1-12), and days of the week (0-7, where both 0 and 7 represent Sunday).

The following special characters can be used in cron expressions:

• *: Represents any value (e.g., * in the hours field means "every hour")
• ,: Specifies a list of values (e.g., 1,15 in the days of the month field means "the 1st and 15th")
• -: Specifies a range of values (e.g., 1-5 in the days of the week field means "Monday to Friday")
• /: Specifies an interval (e.g., */2 in the hours field means "every 2 hours")

on:
  schedule:
    - cron: '30 2 * * 1-5'

In this example, the workflow is scheduled to run at 2:30 AM, Monday through Friday.

Scheduled Workflow Examples

Here are a few more examples of scheduled workflows:

• Run a workflow every 15 minutes:

on:
  schedule:
    - cron: '*/15 * * * *'

• Run a workflow every Monday at 9:00 AM:

on:
  schedule:
    - cron: '0 9 * * 1'

• Run a workflow on the 1st and 15th of each month at 6:00 PM:

on:
  schedule:
    - cron: '0 18 1,15 * *'

Manual Workflows

Manual workflows enable developers to run GitHub Actions workflows on-demand, rather than relying on events. This gives you more control over when certain actions should be executed and makes it easy to test and debug your workflows.

Workflow_dispatch Event

To create a manual workflow, you need to use the workflow_dispatch event in your workflow configuration file (.github/workflows/workflow.yml). This event allows you to trigger the workflow manually from the GitHub Actions interface.

on:
  workflow_dispatch:

With this configuration, the workflow can be triggered at any time by visiting the "Actions" tab in your GitHub repository, selecting the specific workflow, and clicking on the "Run workflow" button.

Configuring Manual Inputs

You can also configure input parameters for your manual workflows. This allows you to pass custom data to the workflow when triggering it manually. To configure input parameters, add an inputs field under the workflow_dispatch event in your workflow configuration file.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'

In this example, an input parameter named environment has been added to the workflow. The parameter has a description, is marked as required, and has a default value of 'staging'. You can access the input parameters in your workflow steps using the github.event.inputs context.

steps:
  - name: Deploy to environment
    run: echo Deploying to ${{ github.event.inputs.environment }}

Running Manual Workflows

Once you have configured a manual workflow with the workflow_dispatch event (and optional input parameters), you can trigger it from the GitHub repository's "Actions" tab.

1. Navigate to the "Actions" tab in your GitHub repository.
2. Select the workflow you want to run from the list of available workflows.
3. Click the "Run workflow" button.
4. If the workflow has input parameters, you will be prompted to enter their values. After providing the required values, click the "Run workflow" button again to trigger the workflow.

Combining Triggers

In many cases, you might want to trigger a workflow based on multiple events or conditions. In this chapter, I will explore how to combine different triggers to create more complex workflows that cater to your project's specific needs.

To combine triggers, you simply need to list them under the on keyword in your workflow configuration file (.github/workflows/workflow.yml). By doing this, the workflow will be triggered when any of the listed events occur.

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

In this example, the workflow is triggered when a push event occurs on the main branch, a pull request event occurs targeting the main branch, or the workflow is manually triggered using the workflow_dispatch event.

Here are a few more examples of combined triggers:

• Trigger a workflow on push events for specific branches and on the creation of a new release:

on:
  push:
    branches:
      - main
      - develop
  release:
    types:
      - created

• Trigger a workflow on issue events (opened or reopened) and on schedule (every day at midnight):

on:
  issues:
    types:
      - opened
      - reopened
  schedule:
    - cron: '0 0 * * *'

• Trigger a workflow on pull request events for specific branches and on manual trigger with an input parameter:

on:
  pull_request:
    branches:
      - main
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'

References

https://docs.github.com/en/actions/reference/events-that-trigger-workflows