Here, you’ll learn about some common configurations in a workflow file. You’ll also explore event type categories, disabling and deleting workflows, and using specific versions of an action to follow security best practices.

Configure workflows to run on scheduled events

As mentioned earlier, you can configure your workflows to run when a specific activity occurs on GitHub, when an external event happens, or at a scheduled time.
The scheduled event allows you to trigger a workflow at specific UTC times using POSIX cron syntax.
This cron syntax consists of five fields represented by asterisks (*), and each field corresponds to a unit of time.

For example, if you want to run a workflow every 15 minutes, the scheduled event would look like the following example:

on:
  schedule:
    - cron:  '*/15 * * * *'

on:
  schedule:
    - cron:  '*/15 * * * *'

And if you want to run a workflow every Sunday at 3:00 a.m., the scheduled event would look like this:

on:
  schedule:
    - cron:  '0 3 * * SUN'

on:
  schedule:
    - cron:  '0 3 * * SUN'

You can also use operators to specify a range of values or refine the scheduled execution of your workflow.
The shortest interval for running scheduled workflows is every five minutes, and they run on the latest commit of the default or base branch.

Configure workflows to run manually

In addition to scheduled events, you can manually trigger a workflow using the workflow_dispatch event.
This event allows you to run the workflow via the GitHub REST API or by selecting the Run workflow button in the Actions tab of your repository on GitHub.
With workflow_dispatch, you can choose which branch to run the workflow on and define optional inputs that GitHub displays as fields in the user interface.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

In addition to workflow_dispatch, you can use the GitHub API to trigger a webhook event called repository_dispatch.
This event allows you to trigger a workflow for an activity that occurs outside of GitHub.
It essentially works like an HTTP request sent to your repository, asking GitHub to start a workflow from an action or a webhook.

Using this manual event requires two steps:

1. Send a POST request to the GitHub endpoint /repos/{owner}/{repo}/dispatches with the webhook event names in the request body.
2. Configure your workflow to use the repository_dispatch event.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

on:
  repository_dispatch:
    types: [opened, deleted]

Configure workflows to run on webhook events

Finally, you can configure a workflow to run when specific webhook events occur on GitHub.
Most webhook events can be triggered by multiple activity types.
If multiple activities exist for a webhook, you can specify an activity type to trigger the workflow.

For example, you can run a workflow for the check_run event, but only for the activity types rerequested or requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch is a custom event in GitHub Actions that allows external systems (or even other GitHub workflows) to manually trigger workflows by sending a POST request to the GitHub API.
This enables flexible automation and integration with tools, scripts, or external systems that need to start workflows in your repository.

Use cases

• Trigger workflows from external CI/CD tools.
• Coordinate multi-repository deployments (e.g., Repository A finishes a build → triggers Repository B).
• Launch automation based on external events (webhooks, monitoring alerts, CRON tasks outside GitHub).
• Chain workflow execution between multiple repositories or within monorepos.

Example of a workflow listening to repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Key elements:

• types: Optional. Defines custom event types such as run-tests, deploy-to-prod, etc.
• github.event.client_payload: Allows access to additional custom data passed in the dispatch event.
• github.event.action: Name of the event_type sent.

Triggering the event via the API

You must send a POST request to the following GitHub REST API v3 endpoint:

/repos/{owner}/{repo}/dispatches

POST https://api.github.com/repos/OWNER/REPO/dispatches

POST https://api.github.com/repos/OWNER/REPO/dispatches

Authorization

Requires a Personal Access Token (PAT) with repo permission.
For organizations, make sure your token’s access settings are properly configured.

Structure of an example command

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Structure of the payload

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Parameters

Details of repository_dispatch parameters

When you make a POST request to the GitHub API endpoint, you must include a JSON body containing two main parameters:

event_type

• Type: string
• Required: Yes
• Description: A custom string you define. GitHub treats this value as the “action” or “type” of the dispatch. It is used to identify what triggered the workflow and to filter workflows that listen for specific types.
• Examples: "deploy", "run-tests", "sync-db", "build-docker"
• Usage in the workflow: Allows listening for specific event types and accessing this value within the workflow. This makes it easier to reuse the same workflow for multiple purposes and keeps automation more organized and event-driven.

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

A freely structured JSON object that allows you to send custom data with the dispatch event.
You define its structure, and it is accessible inside the workflow.

Format:

• Type: object
• Custom keys and values

Usage in the workflow:
This object is used for:

• multi-environment deployments,
• versioned releases,
• or passing context from another system or pipeline.

It enables creating parameterized workflows, similar to using input arguments.

Example:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

Breakdown of an example payload

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Using conditional keywords

In your workflow file, you can access context information and evaluate expressions.
Although expressions are commonly used with the conditional keyword if in a workflow file to determine whether a step should run or not, you can use any supported context and expression to create a condition.

It’s important to know that when you use conditions in your workflow, you must use the specific syntax:

${{ <expression> }}

This syntax tells GitHub to evaluate an expression rather than treat it as a simple string.

Example:
A workflow that uses the if condition to check whether github.ref (the branch or tag that triggered the workflow run) matches refs/heads/main.
For the workflow to continue, it would look like this:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Notice that in this example, the syntax ${{ }} is missing.
With certain expressions, such as the if condition, you can omit the expression syntax.
GitHub automatically evaluates some of these common expressions, but you can still include the ${{ }} syntax in case you forget which ones are evaluated automatically.

For more information on workflow syntax and expressions, see the documentation: Workflow syntax for GitHub Actions.

Disabling and deleting workflows

After adding a workflow to your repository, you might encounter a situation where you want to temporarily disable it.
You can prevent a workflow from being triggered without deleting the file from the repository, either through the GitHub interface or the GitHub REST API.
When you want to re-enable the workflow, you can easily do so using the same methods.

Disabling a workflow can be useful in the following situations:

• An error in a workflow generates too many requests (or incorrect requests) that negatively affect external services.
• You want to temporarily pause a non-critical workflow that consumes too many minutes on your account.
• You need to suspend a workflow that sends requests to a service that is currently offline.
• You are working on a fork and do not need all the features of certain included workflows (such as scheduled workflows).

You can also cancel a running workflow execution from the GitHub interface (Actions tab) or by using the GitHub API with the following endpoint:

DELETE /repos/{owner}/{repo}/actions/runs/{run_id}

DELETE /repos/{owner}/{repo}/actions/runs/{run_id}

Using an organization workflow template

If you have a workflow used by multiple teams within an organization, you don’t need to recreate it in every repository.
You can promote consistency across your organization by using a workflow template defined in the organization’s .github repository.

• Any member of the organization can use a workflow template.
• All repositories in the organization have access to these workflow templates.

How to find them:

1. Go to the Actions tab of a repository in the organization.
2. Click New workflow.
3. Look for the section titled Workflows created by [organization name].

For example, an organization called Mona provides a workflow template as shown here.

Using specific versions of an action

When you reference actions in your workflow, it is recommended to use a specific version of the action rather than simply mentioning the action itself.
By referencing a precise version, you protect yourself against unexpected changes that could be made to the action and potentially break your workflow.

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Some references are more secure than others.
For example, referencing a specific branch runs the action from the latest changes in that branch, which may or may not be desirable.
On the other hand, referencing a version number or a commit SHA hash gives you more precision about the version of the action you are running.

For greater stability and security, it is recommended to use the commit SHA of a published action in your workflows.