Customizing the on directive

The on keyword in GitHub Actions is used to trigger workflows based on specific events that occur in a GitHub repository. It is a crucial part of defining a workflow in GitHub Actions and determining when the workflow should run. In this topic, you will become familiar with a couple of ways to customize the on keyword.

Basic syntax of on directive

The on directive is a key component of GitHub Actions that you can use to specify events that trigger your workflow. The basic syntax of the on directive is:

on:
  [event]: 
    [activity-type]

In this snippet, <event> is the name of the event that will trigger the workflow and <activity-type> is the specific activity that will trigger the workflow within that event.

For example, if you want your workflow to trigger when someone opens a pull request, you would use the on directive in the following way:

on:
  pull_request:
    opened

This snippet tells GitHub Actions to trigger the workflow when a pull request is opened. However, we have only looked at implementing single-event triggers. Let's look at how you can include multiple events as a trigger.

Multiple events

Multiple events in GitHub Actions refers to the ability to trigger a workflow in response to multiple events. With the on directive, you can include multiple event types in a single workflow definition to trigger the workflow for different types of events. This allows you to automate more complex tasks and ensure that your workflows are triggered in response to a wider range of actions.

For example, you can set on: [push, pull_request] to trigger a workflow for both push and pull requests. In such a case, the workflow will run whenever there is a new push or pull request in your repository.

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, reopened, synchronize]

In this example, the workflow is triggered for two events: when pushed to the main branch and when pull request is opened, reopened, or synchronized.

Branches and tags

When setting up a workflow in GitHub Actions, you may want to specify the branches or paths that should trigger the workflow. To achieve this, you can use the on.push event along with the branches and paths parameters.

The branches parameter allows you to specify branches that should trigger the workflow. In order to trigger a workflow only when it is pushed to the main branch, you can use the following syntax:

on:
  push:
    branches:
      - main

You can also use wildcards to match multiple branches. You can use the following snippet to trigger the workflow when there is a push to any branch that starts with feature/:

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

The paths parameter allows you to specify paths of files that should trigger the workflow. If you want to trigger the workflow when there is a push that includes changes to any JavaScript file in the src/ directory, you can use the following syntax:

on:
  push:
    paths:
      - 'src/**/*.js'

In this example, ** is a wildcard that matches any subdirectory under src/. Note that the paths parameter only works for push events, and not for other events like pull_request.

Pull request reviews

You can trigger a workflow in response to a pull request review using the pull_request_review event type. This allows you to automate tasks based on the review process, such as running tests when a review is submitted or notifying team members when a review is approved.

To use the pull_request_review event type, include it in the on keyword of your workflow file, as shown below:

on:
  pull_request_review:
    types: [submitted, edited, dismissed]

In this example, the workflow is triggered when a pull request review is submitted, edited, or dismissed. You can customize the types of events that will trigger the workflow by changing the types parameter.

Once the workflow is triggered, you can use if conditional to check the state of review and run specific tasks based on the result.

jobs:
  test:
    runs-on: ubuntu-latest
    if: github.event.review.state == 'approved'
    steps:
      - run: npm test

In this example, the test job runs only if the pull request review is approved. You can use other review states like changes_requested or commented to trigger different tasks in your workflow.

Issues

The issues event type is used to trigger a workflow when an issue is opened, edited, deleted, transferred, pinned, unpinned, closed, reopened, assigned, unassigned, labeled, or unlabeled. This event type is particularly useful for tracking the progress of issues and ensuring that all necessary actions are taken in response to these events.

Suppose you want to run a workflow whenever a new issue is opened in your repository. You can use the following code in your workflow file:

name: Issue Workflow
on:
  issues:
    types: [opened]
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v2
      - name: Run Script
        run: |
          echo "New issue has been opened!"

Here, the workflow gets triggered only when a new issue is opened, as specified by the types parameter. The workflow consists of a single job, which checks out the repository code and runs a simple script to print a message indicating that a new issue has been opened. You can customize this workflow to perform other actions, such as sending notifications, assigning the issue to a particular user, or updating the issue status.

Fork

When someone creates a fork of your repository, they are essentially creating a copy of your repository under their own GitHub account. This allows them to change the code without affecting your original repository. However, if you want to ensure that certain workflows run on forks as well, you can add a custom on keyword to your workflow configuration.

Here's an example of how to use the on keyword to trigger a workflow on a fork:

name: My Workflow

on:
  fork:

jobs:
  my_job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      # Add more steps as needed...

Label

To trigger your workflow, you can set it up to run when a label is created or modified within your workflow's repository.

If you want your workflow to run when a label is added or removed from an issue, pull request, or discussion, you should use the labeled or unlabeled activity types for the following events:

• issues
• pull_request

Using these activity types, you can ensure that your workflow runs whenever a label is added or removed from any of these entities, rather than just within your repository.

name: label-triggered-workflow

on:
  # Trigger the workflow when a label is created or modified in the repository.
  issues:
    types: [labeled]
  pull_request:
    types: [labeled]

jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: My Action
        run: echo "My Action was executed!"

In this example, the workflow is triggered when a label is created or modified within the repository's issues or pull requests.

Watch

Using the watch event, you can set up a GitHub Actions workflow to run whenever a user watches a repository. This can be useful for a variety of purposes, such as sending notifications or performing certain actions when someone starts following a repository. For example, you can run a workflow when someone stars a repository using the started activity type for a watch event.

Here's a YAML code example that triggers a workflow when someone stars a repository:

name: star-triggered-workflow

on:
  # Trigger the workflow when someone stars the repository
  watch:
    types: started

jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: My Action
        run: echo "My Action was executed!"

In this example, the workflow is triggered when someone stars the repository.

Status

For testing purposes, it is essential to understand and utilize the right events that trigger your workflows and ensure that your code functions as expected. The status keyword in GitHub Actions allows you to trigger a workflow when the status of a Git commit changes. The status of a commit can be marked as error, failure, pending, or success. When the status changes, the workflow will be initiated. If you want to add additional information about the status change, try using the check_run event.

Here's a workflow that uses the status keyword:

name: Build and Deploy
on:
  status
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Build app
        run: npm build
      - name: Deploy app
        if: github.event.state == 'success'
        run: npm deploy

In this code snippet, the workflow is triggered whenever a commit status changes to either success or failure. The deploy step only runs if the commit status is success. It runs the npm deploy command to deploy the application. By using the status keyword, you can ensure that your workflow runs only when the specified commit status changes. This allows you to automate tasks like building and deploying your application with greater precision.

Conclusion

In conclusion, customizing the on keyword in GitHub Actions provides a flexible way to automate tasks in response to events in GitHub repositories. By using the right event types, you can ensure that your workflows run at the right time and respond to the right events, making your automation processes more efficient and effective. You can explore the documentation and learn more about how to customize the on keyword.