Configure a GitHub Actions workflow

Here, you learn some common configurations within a workflow file. You also explore the categories of event types, disabling and deleting workflows, and using specific versions of an action for security best practices.

Configure workflows to run for scheduled events

As mentioned previously, you can configure your workflows to run when specific activity occurs on GitHub, when an event outside of GitHub happens, or at a scheduled time. The schedule event allows you to trigger a workflow to run at specific UTC times using POSIX cron syntax. This cron syntax has five * fields, and each field represents a unit of time.

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

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

And if you wanted to run a workflow every Sunday at 3:00am, the schedule event would look like this:

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

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

Configure workflows to run for manual events

In addition to scheduled events, you can manually trigger a workflow by using the workflow_dispatch event. This event allows you to run the workflow by using the GitHub REST API or by selecting the Run workflow button in the Actions tab within your repository on GitHub. Using workflow_dispatch, you can choose on which branch you want the workflow to run, and set optional inputs that GitHub presents as form elements in the UI.

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 activity that occurs outside of GitHub. It essentially serves as an HTTP request to your repository asking GitHub to trigger a workflow off an action or webhook. Using this manual event requires you to do two things: send a POST request to the GitHub endpoint /repos/{owner}/{repo}/dispatches with the webhook event names in the request body, and 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"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Configure workflows to run for webhook events

Lastly, you can configure a workflow to run when specific webhook events occur on GitHub. You can trigger most webhook events from more than one activity for a webhook. 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 rerequested or requested_action activity types.

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. It enables flexible automation and integration with outside tools, scripts, or systems that need to start workflows in your repo.

Use cases

• Trigger workflows from external CI/CD tools.

• Coordinate multi-repo deployments (for example, Repo A finishes build → triggers Repo B).

• Start automation based on external events (webhooks, monitoring alerts, CRON jobs outside GitHub).

• Chain workflow executions between repositories or within monorepos.

Example workflow that listens 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 }}"

Key elements:

• types: Optional. Defines custom event types like run-tests, deploy-to-prod, etc.

• github.event.client_payload: Access to any other custom data passed in the dispatch event.

• github.event.action: Name of the event_type sent.

Triggering the event via API

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

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

Authorization

• Requires a personal access token (PAT) with repo scope.
• For organizations, ensure proper access settings for your token.

Sample command structure

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"}}'

Payload structure

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

Parameters

Field	Type	Description	Required
event_type	string	A custom name for the event. This name maps to the types value in your workflow trigger	Yes
client_payload	object	Arbitrary JSON payload to send custom data to the workflow (github.event.client_payload)	No

Repository_dispatch parameters breakdown

When making a POST request to the GitHub API endpoint, you must pass a JSON body with two main parameters:

• event_type
• client_payload

event_type

A required custom string that you define. GitHub treats this value as the "action" or "type" of the dispatch. It’s used to identify what triggered the workflow and filter workflows that are listening for specific types.

• Format:

  • Type: string
  • Example: "deploy", "run-tests", "sync-db", "build-docker"

• Use in Workflow: Used in listening for specific event types and accessing the value inside the workflow. This helps with the reuse of a single workflow for multiple purposes and makes automation more organized and event-driven.

• Example:

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

client_payload

A free-form JSON object that lets you send custom data along with the dispatch. You define the structure, and it's accessible inside the workflow.

• Format:

  • Type: object
  • Custom keys and values

• Use in Workflow: This object is used for multi-environment deployments, versioned releases, or passing context from another system or pipeline and enables parameterized workflows, similar to input arguments.

• Example:

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

Example payload breakdown

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

Use conditional keywords

Within your workflow file, you can access context information and evaluate expressions. Although expressions are commonly used with the conditional if keyword in a workflow file to determine whether a step should run or not, you can use any supported context and expression to create a conditional. It's important to know that when using conditionals in your workflow, you need to use the specific syntax ${{ <expression> }}. This syntax tells GitHub to evaluate an expression rather than treat it as a string.

For example, a workflow that uses the if conditional to check if the github.ref (the branch or tag ref that triggered the workflow run) matches refs/heads/main. In order to proceed, the workflow would look something like this:

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

Notice that in this example, the ${{ }} are missing from the syntax. With some expressions, like the if conditional, you can omit the expression syntax. GitHub automatically evaluates some of these common expressions, but you can always include them in case you forget which expressions GitHub automatically evaluates.

For more information about workflow syntax and expressions, check out Workflow syntax for GitHub Actions.

Disable and delete workflows

After adding a workflow to your repository, you might find a situation where you want to temporarily disable the workflow. You can stop a workflow from being triggered without having to delete the file from the repo, either on GitHub or through the GitHub REST API. When you wish to enable the workflow again, you can easily do it using the same methods.

Disabling a workflow can be useful in some of the following situations:

• An error on a workflow is producing too many or wrong requests impacting external services negatively.
• You want to temporarily pause a workflow that isn't critical and is consuming too many minutes on your account.
• You want to pause a workflow that's sending requests to a service that is down.
• You're working on a fork, and you don't need all the functionality of some workflows it includes (like scheduled workflows).

You can also cancel a workflow run that's in progress in the GitHub UI from the Actions tab or by using the GitHub API endpoint DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. Keep in mind that when you cancel a workflow run, GitHub cancels all of its jobs and steps within that run.

Use an organization's templated workflow

If you have a workflow that multiple teams use within an organization, you don't need to re-create the same workflow for each repository. Instead, you can promote consistency across your organization by using a workflow template defined in the organization's .github repository. Any member within the organization can use an organization template workflow, and any repository within that organization has access to those template workflows.

You can find these workflows by navigating to the Actions tab of a repository within the organization, selecting New workflow, and then finding the organization's workflow template section titled "Workflows created by organization name". For example, the organization called Mona has a template workflow as shown here.

Use specific versions of an action

When referencing actions in your workflow, we recommend that you refer to a specific version of that action rather than just the action itself. By referencing a specific version, you're placing a safeguard from unexpected changes pushed to the action that could potentially break your workflow. Here are several ways you can reference a specific version of an action:

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 safer than others. For example, referencing a specific branch runs that action off of the latest changes from that branch, which you might or might not want. By referencing a specific version number or commit SHA hash, you're being more specific about the version of the action you're running. For more stability and security, we recommend that you use the commit SHA of a released action within your workflows.