GitHub Actions Workflow Triggers: A Comprehensive Categorization

GitHub Actions has revolutionized how developers integrate continuous integration and continuous deployment (CI/CD) into their projects. One of its most powerful features is the ability to initiate workflows based on a variety of events. In this post, we’ll categorize these workflow triggers to provide a clearer understanding of when and why you might want to use them.

1. Code & Repository Events
   These triggers are your workhorses. They primarily concern the repository’s codebase and its changes.
   - push: Triggered when commits are pushed to the repository, it’s frequently used to run tests or initiates deployments.
   - pull_request: Activated during pull request actions, this is valuable for running tests against proposed changes before merging.
   - release: Use this when you want to execute tasks like deploying a new version of your software when a new release is cut.
   - create/delete: These concern branch or tag creation and deletion, respectively.
2. Manual & Scheduled Events
   Sometimes, you need more control over when your workflows run.
   - workflow_dispatch: This allows you to manually trigger workflows right from the GitHub UI.
   - schedule: Want to run nightly builds? This trigger uses CRON syntax to run workflows at specified intervals.
3. Issue and & PR Comment Events
   These are all about the discussions happening in your repository.
   - issues: Whether it’s opened, edited, or closed, you can respond to issue activity.
   - issue_comment: This captures comments on issues, letting you automate responses or actions based on discussions.
   - pull_request_review/pull_request_review_comment: These are specialized for the review process of pull requests.
4. External & Custom Events
   For when you need to venture outside the box or want to establish your own trigger events.
   - repository_dispatch: Through the GitHub API, this allows external sources to kick off your workflows. For an in-depth exploration of this trigger, see my previous post: Ringing the Doorbell of your GitHub Repository with ‘repository_dispatch’.
   - workflow_run: A meta-trigger, this lets you initiate workflows based on other workflow outcomes.
   - workflow_call: For the DRY enthusiasts, this is all about reusable workflows. Lets you reuse parts of other workflows so you don’t have to write the same stuff again.
   See my previous post: GitHub Actions: workflow_run vs. workflow_call
5. GitHub Product Features.
   For the GitHub power users making the most of GitHub’s ecosystem.
   - project, project_card, project_column: Automate actions around GitHub’s project boards.
   - label: Whether you’re creating, editing, or deleting, automate actions around labels.
6. Miscellaneous Events
   - fork: Actions to take when your repository is forked.
   - watch: Capture the moment someone starts your repository!
   - page_build: For those using GitHub Pages, respond to build events.
7. Security & Administration
   Protecting the integrity and security of your codebase.
   - branch_protection_rule: Ensure your branch protection rules are enforced.
   - check_run, check_suite: Integrate with the Checks API for additional checks on your code.

Conclusion

Understanding GitHub Actions triggers is fundamental to effectively automating your developer workflows. By categorizing them, we hope to have provided a clearer picture of thier use-cases and potential.

For a more detailed dive into each trigger and their specific use-cases, refer to the official GitHub documentation on triggering workflows and events that trigger workflows.