Automate Your Code with GitHub Actions #2: Events and Triggers in GitHub Actions

Understanding these components is essential to creating effective automation pipelines and customizing workflows to meet your specific requirements.

Who is Bas Steins?

Bas is a software developer and technology trainer based in the triangle between the Netherlands, Germany, and Belgium. For almost two decades, he has been helping people turn their ideas into software and helping other developers write better code. This series is based on his mini-guide "Automate Your Code with GitHub Actions".

Triggers for Events

An event is a specific activity that triggers a workflow. GitHub Actions supports a wide range of events, such as code pushes, pull requests, issue comments, and more. You can configure workflows to run on one or more events, allowing you to automate various tasks based on specific activities in your repository.

In our first workflow, we've already seen the push and the pull_request event:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

Each event can have additional configuration options, such as filtering by branches, paths, or tags. Here are some common event types and their use cases:

• Push: Triggers the workflow on code pushes to the repository. Useful for running tests, linting, or deploying changes.
• Pull Request: Triggers the workflow when a pull request is opened, synchronized, or closed. Ideal for running tests, code analysis, or notifying team members.
• Issue Comment: Triggers the workflow when a comment is added to an issue or pull request. Great for automating issue triage, labeling, or closing stale issues.
• Schedule: Triggers the workflow at specific times or intervals. Perfect for running maintenance tasks, generating reports, or sending reminders.
• Repository Dispatch: Triggers the workflow via an external event using the GitHub API. Enables integration with external services, custom webhooks, or manual triggers.
• Workflow Dispatch: Triggers the workflow manually from the Actions tab in the repository. Useful for ad-hoc runs, debugging, or triggering complex workflows.
• Workflow Call: Triggers the workflow when another workflow calls it. This event is useful for creating reusable workflows or modularizing complex workflows.

Since GitHub Actions is deeply integrated into the whole GitHub ecosystem, there are tons of other events that can trigger a workflow. You can find the full list of supported events in the official documentation.

Here are some examples:

• Gollum: Triggers the workflow when a Wiki page is created or updated. Useful for tracking documentation changes or updating a website.
• Project: Triggers the workflow when a project card is created, updated, moved, or deleted. Great for automating project management tasks or tracking progress.
• Release: Triggers the workflow when a new release is published. Ideal for automating release notes, versioning, or deployment tasks.
• Security Advisory: Triggers the workflow when a security advisory is published or updated. Critical for automating security checks, vulnerability scanning, or compliance tasks.

Contexts

Each event provides a set of contexts that contain information about the event, such as the event type, the repository, the commit, the pull request, and more. You can use these contexts to access data related to the event and make decisions in your workflow.

For example, the push event provides the following contexts:

• github.event_name: The name of the event that triggered the workflow.
• github.repository: The repository where the event occurred.
• github.ref: The Git reference (branch or tag) that triggered the workflow.
• github.sha: The commit SHA that triggered the workflow.
• github.actor: The username of the user that triggered the workflow.
• github.head_ref: The head branch of the pull request.
• github.base_ref: The base branch of the pull request.

You can access these contexts in your workflow using the github object. For example, to print the commit SHA that triggered the workflow, you can use the following step:

- name: Print commit SHA
  run: echo ${{ github.sha }}

By using contexts, you can create dynamic workflows that respond to specific events and conditions in your repository.

The push Event

The push event triggers the workflow when a commit is pushed to the repository. This event is useful for running tests, linting, or deploying changes. You can configure the push event to run on specific branches, tags, or paths.

Here is an example workflow that triggers on the push event:

name: Push Event
on:
  push:
    branches:
      - main
      - feature/*
    tags:
      - v1.*
    paths:
      - 'src/**'

In this workflow, the push event is configured to run on the main branch, any branch that starts with feature/, tags that match the pattern v1.*, and changes in the src/ directory.

You can use the push event to automate tasks such as: running tests on every commit, deploying changes to a staging environment, notifying team members of new commits, and generating release notes based on commit messages.

The push Context

When the push event triggers a workflow, it provides a set of contexts that contain information about the event. You can use these contexts to access data related to the push event and make decisions in your workflow.

Here are some common contexts provided by the push event:

• github.event_name: The name of the event that triggered the workflow (push).
• github.repository: The repository where the event occurred.
• github.ref: The Git reference (branch or tag) that triggered the workflow.
• github.sha: The commit SHA that triggered the workflow.
• github.actor: The username of the user that triggered the workflow.
• github.head_ref: The head branch of the push event.
• github.base_ref: The base branch of the push event.

The pull_request Event

The pull_request event triggers the workflow when a pull request is opened, synchronized, or closed. This event is ideal for running tests, code analysis, or notifying team members. You can configure the pull_request event to run on specific branches, paths, or labels.

Here is an example workflow that triggers on the pull_request event:

name: Pull Request Event
on:
  pull_request:
    branches:
      - main
      - feature/*
    paths:
      - 'src/**'
      - '!src/experimental/**'

In this workflow, the pull_request event is configured to run on the main branch, any branch that starts with feature/, and changes in the src/ directory excluding the src/experimental/ directory.

You can use the pull_request event to automate tasks such as: running tests on every pull request, code analysis and linting, notifying team members of new pull requests, and automatically labeling pull requests based on changes.

The pull_request Context

When the pull_request event triggers a workflow, it provides a set of contexts that contain information about the event. You can use these contexts to access data related to the pull request event and make decisions in your workflow.

Here are some common contexts provided by the pull_request event:

• github.event_name: The name of the event that triggered the workflow (pull_request).
• github.repository: The repository where the event occurred.
• github.ref: The Git reference (branch or tag) that triggered the workflow.
• github.sha: The commit SHA that triggered the workflow.
• github.actor: The username of the user that triggered the workflow.
• github.head_ref: The head branch of the pull request.
• github.base_ref: The base branch of the pull request.

The schedule Event

The schedule event triggers the workflow at specific times or intervals. This event is perfect for running maintenance tasks, generating reports, or sending reminders. You can configure the schedule event to run on a cron schedule or at specific times.

Here is an example workflow that triggers on the schedule event:

name: Scheduled Event
on:
  schedule:
    - cron: '0 0 * * *'

In this workflow, the schedule event is configured to run every day at midnight (00:00 UTC).

You can use the schedule event to automate tasks such as: running daily backups, generating weekly reports, sending monthly reminders, and cleaning up stale data.

To understand the cron syntax, here is a quick reference:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * *

The schedule Context

When the schedule event triggers a workflow, it provides a set of contexts that contain information about the event. Here are some common contexts provided by the schedule event:

• github.event_name: The name of the event that triggered the workflow (schedule).
• github.repository: The repository where the event occurred.
• github.ref: The Git reference (branch or tag) that triggered the workflow.
• github.sha: The commit SHA that triggered the workflow.
• github.actor: The username of the user that triggered the workflow.

The issues Event

The issues event triggers the workflow when an issue is opened, edited, deleted, transferred, pinned, unpinned, closed, reopened, assigned, unassigned, labeled, unlabeled, locked, unlocked, milestoned, or demilestoned. This event is ideal for automating issue triage, labeling, or closing stale issues. You can configure the issues event to run on specific labels, assignees, or milestone changes.

Here is an example workflow that triggers on the issues event:

name: Issue Event
on:
  issues:
    types: [opened, edited, closed]
    branches:
      - main
    labels:
      - bug
      - enhancement

In this workflow, the issues event is configured to run on the main branch when an issue is opened, edited, or closed with the labels bug or enhancement.

You can use the issues event to automate tasks such as: labeling issues based on content, assigning issues to team members, closing stale or resolved issues, and notifying team members of new or updated issues.

The issues Context

When the issues event triggers a workflow, it provides a set of contexts that contain information about the event. Here are some common contexts provided by the issues event:

• github.event_name: The name of the event that triggered the workflow (issues).
• github.repository: The repository where the event occurred.
• github.ref: The Git reference (branch or tag) that triggered the workflow.
• github.sha: The commit SHA that triggered the workflow.
• github.actor: The username of the user that triggered the workflow.
• github.head_ref: The head branch of the issue event.
• github.base_ref: The base branch of the issue event.

Dispatch Events

The repository_dispatch Event

The repository_dispatch event triggers the workflow when a repository dispatch event is sent to the repository. This event is ideal for triggering workflows from external systems or services. You can configure the repository_dispatch event to run on specific types of events or with custom payloads.

Here is an example workflow that triggers on the repository_dispatch event:

name: Repository Dispatch Event
on:
  repository_dispatch:
    types: [my-event-type]

In this workflow, the repository_dispatch event is configured to run when a repository dispatch event of type my-event-type is sent to the repository.

You can use the repository_dispatch event to automate tasks such as: triggering deployments from external systems, running tests from external services, notifying team members of external events, and integrating with third-party services.

The repository_dispatch Context

When the repository_dispatch event triggers a workflow, it provides a set of contexts that contain information about the event. Here are some common contexts:

• github.event_name: The name of the event that triggered the workflow (repository_dispatch).
• github.repository: The repository where the event occurred.
• github.ref: The Git reference (branch or tag) that triggered the workflow.
• github.sha: The commit SHA that triggered the workflow.
• github.actor: The username of the user that triggered the workflow.

To trigger a repository dispatch event, you can use the GitHub API or the GitHub CLI. Here is an example to trigger a repository dispatch event from another workflow:

name: Trigger Repository Dispatch
on:
  push:
    branches:
      - main
jobs:
  trigger_dispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Repository Dispatch
        run: |
          curl -X POST \
            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
            -H "Accept: application/vnd.github.v3+json" \
            https://api.github.com/repos/owner/repo/dispatches \
            -d '{"event_type": "my-event-type", "client_payload": {"key": "value"}}'

The workflow_dispatch Event

The workflow_dispatch event triggers the workflow manually from the Actions tab in the GitHub repository. This event is perfect for running workflows on-demand, testing changes, or deploying specific versions. You can configure the workflow_dispatch event with input parameters to customize the workflow run.

Here is an example workflow that triggers on the workflow_dispatch event:

name: Workflow Dispatch Event
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        default: 'production'

In this workflow, the workflow_dispatch event is configured to run with an input parameter environment that specifies the deployment environment. The input parameter is required and has a default value of production.

You can use the workflow_dispatch event to automate tasks such as: deploying specific versions of the application, running manual tests or validations, triggering custom actions or integrations, and performing maintenance tasks on-demand.

repository_dispatch vs. workflow_dispatch

The repository_dispatch and workflow_dispatch events are both manual triggers for workflows, but they have different use cases and configurations.

• repository_dispatch: Triggered by external systems or services using the GitHub API or GitHub CLI. Can be configured to run on specific event types.
• workflow_dispatch: Triggered manually from the Actions tab in the GitHub repository. Can be configured with input parameters to customize the workflow run.

In the next article, we'll explore how jobs and actions work together to form the backbone of your workflows. See you there!