GitHub Actions triggers: 5 ways to trigger a workflow (with code)

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 using 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.

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 paths-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:

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.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback