Workflow Triggers and Event Filtering

In the world of GitHub Actions, a workflow doesn't just run on its own. It needs a "spark" to start. This spark is known as a trigger. Understanding how to control these triggers through event filtering is essential for building efficient CI/CD pipelines that don't waste compute minutes on unnecessary tasks.

What are Workflow Triggers?

A trigger is a specific activity that instructs GitHub to execute a workflow. These are defined under the on key in your YAML file. Triggers can range from code changes (like a push) to manual button clicks or even scheduled cron jobs.

Common Trigger Types

• push: Runs when code is pushed to the repository.
• pull_request: Runs when a pull request is opened, synchronized, or reopened.
• schedule: Runs at specific times using POSIX cron syntax.
• workflow_dispatch: Allows you to manually trigger a workflow from the GitHub UI.

Event Filtering: Fine-Tuning Your Automation

By default, if you specify on: push, the workflow runs every time anyone pushes anything to any branch. In professional environments, this is rarely what you want. Event filtering allows you to define exactly which conditions must be met for the workflow to trigger.

1. Branch Filtering

You can restrict workflows to run only on specific branches, such as main or release/*.

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

2. Path Filtering

Path filtering is incredibly useful for monorepos. It ensures that a workflow only runs if files in a specific directory have changed. For example, you might only want to run Java tests if the src/main/java folder is modified.

on:
  push:
    paths:
      - 'src/**'
      - 'pom.xml'

3. Tag Filtering

If your team uses Git tags for versioning (e.g., v1.0.0), you can trigger deployment workflows only when a new tag is pushed.

on:
  push:
    tags:
      - 'v*'

Activity Types

Some events have "activity types" that provide even more granular control. For the pull_request event, you might want to trigger a workflow only when a PR is labeled or closed, rather than every time code is pushed to it.

on:
  pull_request:
    types: [opened, reopened, labeled]

Visualizing the Trigger Logic

Understanding the flow of how GitHub evaluates triggers helps in debugging why a workflow did or did not run.

[ GitHub Event Occurs ]
       |
       v
[ Check 'on' Configuration ]
       |
       v
[ Does Event Match? ] ---- No ----> [ Skip Workflow ]
       | Yes
       v
[ Check Filters (Branches/Paths/Tags) ]
       |
       v
[ Do Filters Match? ] ---- No ----> [ Skip Workflow ]
       | Yes
       v
[ Execute Workflow Jobs ]
    

Real-World Use Cases

• Production Deployment: Triggered only on a push to the main branch after a successful pull_request merge.
• Nightly Security Scans: Using the schedule trigger to run dependency checks every night at midnight.
• Documentation Updates: Using paths-ignore to prevent CI tests from running when someone only updates the README.md file.

Common Mistakes to Avoid

• Mixing branches and branches-ignore: You cannot use both branches and branches-ignore for the same event in a single workflow.
• Incorrect Cron Syntax: GitHub Actions schedule triggers use UTC time. Forgetting the time zone difference is a frequent mistake for beginners.
• Path Filtering Limitations: Path filters are not evaluated for certain events like workflow_dispatch.
• YAML Indentation: Triggers are highly sensitive to indentation. Ensure branches is nested correctly under the event name.

Interview Notes: Triggers and Filtering

• Question: How do you trigger a workflow manually?
• Answer: By using the workflow_dispatch event in the YAML file. This adds a "Run workflow" button in the GitHub Actions tab.
• Question: What is the difference between branches and branches-ignore?
• Answer: branches defines an allow-list, while branches-ignore defines a deny-list. You use one or the other to control execution based on the Git branch.
• Question: Can a workflow have multiple triggers?
• Answer: Yes, the on key can accept a list of multiple events, such as on: [push, pull_request].

Summary

Workflow triggers and event filtering are the gatekeepers of your CI/CD process. By mastering the on keyword, using branches and paths filters, and understanding activity types, you can ensure your workflows are precise, cost-effective, and fast. In the next topic, Topic 11: Understanding Runners and Environments, we will explore where these workflows actually execute.

Related Topics in this Course:

• Topic 9: YAML Syntax Deep Dive - Understanding the structure of workflow files.
• Topic 11: Understanding Runners and Environments - Where your code runs after the trigger.
• Topic 12: Working with Jobs and Steps - Defining what happens once a workflow is triggered.