Events that trigger workflows

You can configure your workflows to run when specific activity on GitHub happens, at a scheduled time, or when an event outside of GitHub occurs.

GitHub Actions is currently in limited public beta and is subject to change. We strongly recommend that you do not use this feature for high-value workflows and content during the beta period.

For more information, see "About GitHub Actions."

In this article

Event restrictions

An action in a workflow run can't trigger a new workflow run. For example, if an action pushes code using the repository's GITHUB_TOKEN, a new workflow will not run even when the repository contains a workflow configured to run when push events occur.

Webhook events

You can configure your workflow to run when webhook events are created from activity on GitHub. Workflows can use more than one webhook event to trigger a workflow run. For more information, see "Webhooks" in the GitHub Developer documentation.

Example using one event

on: push

Example using more than one event

# Use an array when using more than one event
on: [push, pull_request]

A workflow runs on a specific version of code in your repository, determined by the commit SHA and Git ref. GitHub determines the commit SHA and Git ref that triggered the event using the webhook event payload. When a workflow runs, GitHub sets the GITHUB_SHA (commit SHA) and GITHUB_REF (Git ref) environment variables in the virtual environment. For more information, see "Environment variables."

You can choose any of these events to trigger a workflow. For information about each webhook event type, see "Event types and payloads" in the GitHub Developer documentation. Each event specifies the origin of the GITHUB_SHA and GITHUB_REF used in the workflow.

Webhook event name GITHUB_SHA GITHUB_REF Event description
check_run Check run commit Check suite branch Triggered when a check run is created, rerequested, completed, or has a requested_action.
check_suite Check suite commit Check suite branch Triggered when a check suite is completed, requested, or rerequested.
commit_comment Commit that was commented on n/a Triggered when a commit comment is created.
create Last commit on the created branch or tag Branch or tag created Represents a created branch or tag.
delete Last commit on default branch Default branch Represents a deleted branch or tag.
deployment Commit to be deployed Branch or tag to be deployed (empty if commit) Represents a deployment. Deployments created with a commit SHA may not have a Git ref.
deployment_status Commit to be deployed Branch or tag to be deployed (empty if commit) Represents a deployment status. Deployments created with a commit SHA may not have a Git ref.
fork Last commit on default branch Default branch Triggered when a user forks a repository.
gollum Last commit on default branch Default branch Triggered when a Wiki page is created or updated.
issue_comment Last commit on default branch Default branch Triggered when an issue comment is created, edited, or deleted.
issues Last commit on default branch Default branch Triggered when an issue is opened, edited, deleted, transferred, pinned, unpinned, closed, reopened, assigned, unassigned, labeled, unlabeled, locked, unlocked, milestoned, or demilestoned.
label Last commit on default branch Default branch Triggered when a repository's label is created, edited, or deleted.
member Last commit on default branch Default branch Triggered when a user accepts an invitation or is removed as a collaborator to a repository, or has their permissions changed.
milestone Last commit on default branch Default branch Triggered when a milestone is created, closed, opened, edited, or deleted.
page_build The commit being built n/a Triggered on push to a GitHub Pages enabled branch (gh-pages for project pages, master for user and organization pages).
project Last commit on default branch Default branch Triggered when a project is created, updated, closed, reopened, or deleted.
project_card Last commit on default branch Default branch Triggered when a project card is created, edited, moved, converted to an issue, or deleted.
project_column Last commit on default branch Default branch Triggered when a project column is created, updated, moved, or deleted.
public Last commit on default branch Default branch Triggered when a private repository is made public.
pull_request Last commit on the GITHUB_REF branch Head branch or base branch if from a fork Triggered when a pull request is assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, synchronize, ready_for_review, locked, unlocked or when a pull request review is requested or removed. See below to learn how this event works with forked repositories.
pull_request_review_comment Last commit on the GITHUB_REF branch Head branch or base branch if from a fork Triggered when a comment on a pull request's unified diff is created, edited, or deleted (in the Files Changed tab). See below to learn how this event works with forked repositories.
pull_request_review Last commit on the GITHUB_REF branch Head branch or base branch if from a fork Triggered when a pull request review is submitted into a non-pending state, the body is edited, or the review is dismissed. See below to learn how this event works with forked repositories.
push Commit pushed, unless deleting a branch (when it's the default branch) Updated ref Triggered on a push to a repository branch. Branch pushes and repository tag pushes also trigger webhook push events. This is the default event.
repository_dispatch Last commit on the GITHUB_REF branch Branch that received dispatch Any time another user or app triggers the event.
release Last commit in the tagged release Tag of release Triggered when a release is published, unpublished, created, edited, deleted, or prereleased.
scheduled Last commit on default branch Default branch When the scheduled workflow is set to run. A scheduled workflow uses POSIX cron syntax. For more information, see "Triggering a workflow with events."
status Commit that changed status n/a Triggered when the status of a Git commit changes.
watch Last commit on default branch Default branch Triggered when someone stars a repository.

Pull request events for forked repositories

When you open a pull request from a forked repository, the pull request opens on the base repository by default. In this scenario, GitHub sends the pull_request event to the base repository and no pull request events occur on the forked repository because the webhook configuration of the original base repository doesn't apply to forked repositories.

The base repository receives a pull_request event where the GITHUB_SHA is the latest commit on the head branch and the GITHUB_REF is the head branch. The version of the workflow file and the code in the pull request is the merge commit SHA. The permissions for the GITHUB_TOKEN in forked repositories is read-only. For more information about the GITHUB_TOKEN, see "Virtual environments for GitHub Actions."

If you intend to use the pull_request event to trigger CI tests, we recommend that you set up your workflow configuration to listen to the push event.

Scheduled events

You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch.

This example triggers the workflow every 15 minutes:

on:
  schedule:
  # * is a special character in YAML so you have to quote this string
  - cron:  '*/15 * * * *'

Cron syntax has five fields separated by a space, and each field represents a unit of time.

┌───────────── 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)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

You can use these operators in any of the five fields:

Operator Description Example
* Any value * * * * * runs every minute of every day.
, Value list separator 2,10 4,5 * * * runs at minute 2 and 10 of the 4th and 5th hour of every day.
- Range of values 0 4-6 * * * runs at minute 0 of the 4th, 5th, and 6th hour.
/ Step values 20/15 * * * * runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50).

Note: GitHub Actions does not support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly, and @reboot.

You can use crontab guru to help generate your cron syntax and confirm what time it will run. To help you get started, there is also a list of crontab guru examples.

External events

You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub. For more information, see "Create a repository dispatch event" in the GitHub Developer documentation.

To trigger the custom repository_dispatch webhook event, you must send a POST request to a GitHub API endpoint and provide an event_type name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the repository_dispatch event.

Example

on: repository_dispatch

Ask a human

Can't find what you're looking for?

Contact us