Workflow Event Filters and Activity Types

In this guide, you’ll learn how to fine-tune GitHub Actions workflows by combining event filters, branch filters, path filters, and activity types. By applying these settings, you can ensure that your CI/CD pipelines run only when relevant code or pull request events occur.

For Pull Request events, you can target specific activities such as opened, closed, or assigned:

The Push event doesn’t support activity types, but you can filter by paths and branches:

Filters and Activity Types Overview

Sample Workflow: workflowfilters.yaml

name: Workflow Filters and Activities

on:
  workflow_dispatch:
  push:
    # Run on pushes to main; ignore feature/* branches
    branches:
      - main
    branches-ignore:
      - 'feature/*'
  pull_request:
    # Trigger only for opened and closed PRs on main
    types:
      - opened
      - closed
    branches:
      - main
    # Skip runs when only README.md changes
    paths-ignore:
      - README.md

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This job ran for event: ${{ github.event_name }}"

1. Push Event Filtering

The push event can be scoped by branch patterns:

• branches: include only these branches.
• branches-ignore: exclude matching branches.
• paths: include only if specified files change.
• paths-ignore: exclude if only specified files change.

Example: trigger on main pushes, ignore feature/* branches.

on:
  push:
    branches:
      - main
    branches-ignore:
      - 'feature/*'

When you push to main, the workflow runs:

Pushing to feature/... branches is ignored:

2. Pull Request Activity Types and Path Filters

You can refine pull_request triggers by:

• types: run workflows on specific PR actions (opened, closed, etc.).
• branches: target only certain base branches.
• paths / paths-ignore: filter by file changes.

on:
  pull_request:
    types:
      - opened
      - closed
    branches:
      - main
    paths-ignore:
      - README.md

2.1 PR with Only README.md Changes

If a PR only updates README.md, the workflow is skipped:

Even closing the PR does not trigger it:

3. PR with Other File Changes

When a PR includes changes beyond README.md—for example, adding ASCII artwork—the workflow triggers on open:

The hello job runs successfully:

Since closed is included in types, closing the PR also triggers the workflow:

Complete Example with Scheduled Triggers

name: Workflow Filters and Activities

on:
  workflow_dispatch:
  schedule:
    - cron: "*/59 * * * *"
  push:
    branches:
      - main
    branches-ignore:
      - 'feature/*'
  pull_request:
    types:
      - opened
      - closed
    branches:
      - main
    paths-ignore:
      - README.md

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Executed for event: ${{ github.event_name }}"

Links and References

• GitHub Actions: Events that trigger workflows
• Workflow syntax for GitHub Actions
• Scheduled events (cron)