GitHub Actions Triggers: 5 Ways to Trigger a Workflow (with Code)

Article Content

What Are GitHub Actions Triggers? 

GitHub Actions triggers are conditions that activate workflows in a repository. They are events prompting automation when certain actions occur in the project. Triggers rely on events, which can range from code pushes, pull requests, or scheduled times. This automation simplifies repetitive tasks.

The integration of triggers within GitHub’s CI/CD pipeline allows teams to create workflows aligned with their development practices. By defining actions that fire the workflows, project management and code quality can improve significantly. Understanding triggers is essential for utilizing GitHub Actions effectively and aligning automation strategies with project requirements.

Understanding Events in GitHub Actions 

Events in GitHub Actions are actions such as pushing a commit or creating an issue. They act as signals for GitHub Actions workflows to start executing. Events can originate from GitHub’s platform, be scheduled, or be defined by users for custom needs.

Built-In Events

Built-in events include the standard set of actions within GitHub, such as commits, pull requests, and releases. These predefined events are integral to the development process and are commonly used to automate testing, deployment, and other tasks. With built-in events, developers can create workflows that respond automatically to frequently occurring actions. 

Custom Events

Custom events allow users to define triggers tailored to unique project requirements. This flexibility ensures that teams can adapt GitHub Actions to meet their needs, optimizing their CI/CD processes while maintaining control over automation. Creating custom events involves defining new triggers and configuring workflows to respond accordingly.

Kostis Kapelonis headshot
Kostis Kapelonis
Senior Developer Evangelist, Octopus Deploy
Kostis is a software engineer/technical-writer dual-class character. He lives and breathes automation, good testing practices, and stress-free deployments with GitOps.

TIPS FROM THE EXPERT

In my experience, here are tips that can help you better optimize GitHub Actions Triggers for effective CI/CD:

  1. Leverage concurrency controls to avoid redundant runs: Use the concurrency key to cancel queued runs when a new event for the same workflow arrives. This is helpful for frequent pushes or pull requests where only the latest run matters.
  2. Use conditional expressions for selective job execution: Instead of creating multiple workflows, use if conditions within job steps to dynamically control execution based on context. For example, only run deployment steps if the branch is main and a specific tag is present.
  3. Optimize secrets management with GitHub Environments: Define secrets in GitHub Environments to scope secrets usage to specific branches or workflow events, adding an extra layer of security. This is especially useful for managing access to sensitive environments like production.
  4. Enable auto-cancel for redundant workflows with concurrency groups: Use concurrency groups with the concurrency: cancel-in-progress setting to ensure only the latest run executes in scenarios with frequent pushes, reducing costs and execution time.
  5. Limit permissions of GITHUB_TOKEN for specific jobs: GitHub Actions’ default permissions for GITHUB_TOKEN can sometimes be excessive. Use permissions to limit what each job can access, improving security by granting only the required permissions.

Quick Tutorial: 5 Ways to Trigger a Workflow in GitHub Actions 

This tutorial provides an overview of how to use triggers in GitHub Actions to initiate a workflow. These instructions are adapted from the GitHub Actions documentation.

1. Using Events to Trigger Workflows

Events in GitHub Actions are defined using the on key in the workflow file. Events specify which actions will initiate the workflow.

  • A single event, like push, triggers the workflow on any branch push:
on: push
  • Multiple events can also be specified, such as push and fork, to trigger a workflow on either action:
on: [push, fork]

When using multiple events, a single occurrence of any specified event will start the workflow. This feature allows workflows to react to a range of repository actions without needing separate workflows.

2. Using Event Activity Types

Some events allow further customization through activity types, providing finer control over workflow execution. For example, the issues event can specify activities like opened and labeled:

on:
  issues:
types:  
  - opened  
  - labeled

With this setup, the workflow triggers when an issue is either opened or labeled. If multiple activity types occur at the same time, GitHub initiates separate workflow runs for each.

3. Using Filters

Filters in GitHub Actions workflows allow users to define conditions under which a workflow should or shouldn’t run. Filters can be used with events such as push or pull_request to specify branches, tags, and file paths that determine when to trigger the workflow. This provides developers with greater control over automation.

Branch Filtering with Push and Pull Request Events

With the push and pull_request events, developers can limit workflow runs to specific branches using the branches filter. Here’s an example:

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

This workflow only triggers on pushes to the main branch or any branch starting with releases/ (like releases/v1.0).

Excluding Branches

To exclude certain branches, use branches-ignore. This example configures a workflow to ignore any push to branches that match the releases/**-alpha pattern:

on:
  push:
branches-ignore:  
  - 'releases/**-alpha'

This workflow won’t run on branches like releases/v1.0-alpha, but will still run on branches like releases/v1.0.

Tag Filtering for Push Events

Tags can also be filtered similarly. Using tags and tags-ignore, users can control which tags trigger a workflow. Here’s an example that only triggers on tags that start with v1.:

on:
  push:
tags:  
  - 'v1.*’

This configuration triggers the workflow for tags such as v1.1 or v1.2.3.

Filtering by File Path

To control workflow execution based on changed files, developers can use paths or paths-ignore. 

  • Using paths: For example, the following setup only triggers the workflow when a .js file is pushed:
on:
  push:
paths:`  
  `- '**/*.js'
  • Using path-ignore: To ignore changes within the docs directory, use paths-ignore. The following workflow will only run if files outside the docs directory are modified.
on:
  push:
paths-ignore:`  
  `- 'docs/**'

4. Triggering a Workflow from a Workflow

In GitHub Actions, workflows can be configured to trigger other workflows. However, workflows triggered by the default GITHUB_TOKEN are limited to avoid recursive triggers that can lead to unintended workflow runs. 

When using GITHUB_TOKEN, events it initiates (except workflow_dispatch and repository_dispatch) will not activate additional workflows, which is helpful to prevent infinite loops.

Example of using GITHUB_TOKEN so that a workflow doesn’t trigger another workflow:Alternatively, using GITHUB_TOKEN to label the issue, as in the following example, will not trigger downstream workflows:

on:
  issues:
    types: 
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit "$ISSUE_URL" --add-label "triage"

Using a personal access token (PAT) to trigger a workflow from another workflow:

If a workflow needs to trigger another workflow, developers can use a personal access token (PAT) or a GitHub App installation access token. This approach allows the new workflow to execute even if it was triggered by a previous workflow. Here’s an example:

on:
  issues:
    types: 
      - opened

jobs:
  label_issue:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.EXAMPLE_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}
        run: |
          gh issue edit "$ISSUE_URL" --add-label "triage"

In this example, a PAT (stored as EXAMPLE_TOKEN in GitHub Secrets) is used to label a newly opened issue. If other workflows are configured to trigger on label addition, they will execute.

5. Defining Inputs for Manually Triggered Workflows

In GitHub Actions, manually triggered workflows use the workflow_dispatch event. This trigger allows users to define inputs that can be specified when manually running the workflow, making it flexible for tasks that need specific parameters.
To define inputs, list them under the inputs section in the workflow_dispatch event. Each input can have properties such as description, required, default, and type.

Best Practices for Using GitHub Actions Triggers 

Implementation of the following practices helps in minimizing errors and improving the reliability of automated tasks.

Be Specific with Trigger Events

Trigger event specificity involves using precise conditions that accurately reflect necessary workflow tasks. By narrowing events to only essential actions, developers can reduce unnecessary workflow executions, optimizing resource use and system performance. This specificity also aids in creating more predictable and manageable automation patterns.

Crafting precise triggers requires a deep understanding of both the events available and the project requirements they should align with. Strategically focusing on relevant events ensures that workflows are efficient and purposeful, leading to cleaner and more reliable automation processes within the development lifecycle.

Handle Pull Requests from Forks in a Secure Manner

Handling pull requests, especially from forks, requires security considerations to prevent malicious code execution. It involves configuring workflows to only run trusted code, maintaining control of external contributions. Ensuring security in this context is crucial for protecting repository integrity and sensitive data.

Implement security measures such as requiring manual permission before executing workflows from forks, or using tokens with limited permissions. By properly configuring these workflows, repositories can welcome external contributions while maintaining a secure CI/CD environment, avoiding unnecessary risks associated with untrusted code.

Use workflow_run Efficiently

The workflow_run trigger allows a workflow to start upon the completion of another. Efficient use of this trigger means designing workflows to execute in logical sequences, improving process flow. By understanding dependency relationships between workflows, developers can create seamless automation chains.

Configuring workflow_run involves setting precise conditions under which follow-up workflows initiate, ensuring that they contribute meaningfully to the development process. Proper usage reduces downtime between processes and ensures continuity, creating a more efficient development pipeline and promoting smoother transitions between workflow stages.

Ensure Proper Documentation and Commenting

Good documentation and commenting within workflows are important for maintaining clarity and usability. Detailed documentation supports developer understanding and collaboration, ensuring consistent project management. Clear comments can highlight logic and execution flows within workflows, aiding in troubleshooting and optimization.

Creating documentation involves detailing the purpose, triggers, and conditions of workflows, keeping all stakeholders informed and aligned. By maintaining accurate and thorough documentation and comments, teams ensure that automation processes are transparent and can be easily understood or modified by both current and future developers.

Test and Debug Workflow Triggers

Testing and debugging are crucial steps in refining workflow triggers, ensuring they perform as expected under various conditions. Developers should incorporate test cases designed to verify the functionality and reliability of workflow automation. Rigorous testing identifies potential issues and optimizes workflow performance before deployment.

Debugging involves monitoring workflow executions and analyzing logs to understand failures or inefficiencies, making adjustments for improvement. By implementing a structured testing and debugging approach, developers can ensure that GitHub Actions workflows remain reliable throughout their lifecycle.

Combine GitHub Actions with Codefresh to Support GitOps and Kubernetes Deployments

GitHub actions is a very powerful platform but it is focused mostly on CI and does not support GitOps and native Kubernetes deployments. Codefresh is created specifically for GitOps and Cloud native applications and includes native support for using GitHub Actions for the CI part of the Software lifecycle.

This means that you can get the best of both worlds by keeping all your CI workflows in GitHub Actions, while using Codefresh for advanced features such as:

  • Application dashboards
  • Git source managements
  • Configuration drift management
  • Kubernetes environment dashboards
  • Topology views

In case you are new to Codefresh – we have made it our mission since 2014 to help teams accelerate their pace of innovation. Codefresh recently released a completely rebuilt GitOps CI/CD toolset. Powered by Argo, Codefresh now combines the best of open source with an enterprise-grade runtime allowing you to fully tap the power of Argo Workflows, Events, CD, and Rollouts. It provides teams with a unified GitOps experience to build, test, deploy, and scale their applications.

Learn more about Codefresh

The World’s Most Modern CI/CD Platform

A next generation CI/CD platform designed for cloud-native applications, offering dynamic builds, progressive delivery, and much more.

Check It Out
Related GitHub Actions articles