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 available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. GitHub Actions is unavailable for per-repository plans, which are legacy billing plans. For more information, see "GitHub's products."

In this article

About workflow 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. For more information about the on syntax, see "Workflow syntax for GitHub Actions."

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.

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 "Using environment variables."

Example using a single event

# Trigger on push
on: push

Example using a list of events

# Trigger the workflow on push or pull request
on: [push, pull_request]

Example using multiple events with activity types or configuration

If you need to specify activity types or configuration for an event, you must configure each event separately. You must append a colon (:) to all events, including events without configuration.

on:
  # Trigger the workflow on push or pull request,
  # but only for the master branch
  push:
    branches:
      - master
  pull_request:
    branches:
      - master
  # Also trigger on page_build, as well as release created events
  page_build:
  release:
    types: # This configuration does not affect the page_build event above
      - created

Webhook events

You can configure your workflow to run when webhook events are created on GitHub. Some events have more than one activity type that triggers the event. If more than one activity type triggers the event, you can specify which activity types will trigger the workflow to run.

Check run event: check_run

Runs your workflow anytime the check_run event occurs. More than one activity type triggers this event. For information about the REST API, see "Check runs" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
check_run - created
- rerequested
- completed
- requested_action
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a check run has been rerequested or requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Check suite event: check_suite

Runs your workflow anytime the check_suite event occurs. More than one activity type triggers this event. For information about the REST API, see "Check suites" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
check_suite - completed
- requested
- rerequested
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a check suite has been rerequested or completed.

on:
  check_suite:
    types: [rerequested, completed]

Create event: create

Runs your workflow anytime someone creates a branch or tag, which triggers the create event. For information about the REST API, see "Create a reference" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
create n/a Last commit on the created branch or tag Branch or tag created

For example, you can run a workflow when the create event occurs.

on:
  create

Delete event: delete

Runs your workflow anytime someone deletes a branch or tag, which triggers the delete event. For information about the REST API, see "Delete a reference" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
delete n/a Last commit on default branch Default branch

For example, you can run a workflow when the delete event occurs.

on:
  delete

Deployment event: deployment

Runs your workflow anytime someone creates a deployment, which triggers the deployment event. Deployments created with a commit SHA may not have a Git ref. For information about the REST API, see "Deployments" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
deployment n/a Commit to be deployed Branch or tag to be deployed (empty if commit)

For example, you can run a workflow when the deployment event occurs.

on:
  deployment

Deployment status event: deployment_status

Runs your workflow anytime a third party provides a deployment status, which triggers the deployment_status event. Deployments created with a commit SHA may not have a Git ref. For information about the REST API, see "Create a deployment status" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
deployment_status n/a Commit to be deployed Branch or tag to be deployed (empty if commit)

For example, you can run a workflow when the deployment_status event occurs.

on:
  deployment_status

Fork event: fork

Runs your workflow anytime when someone forks a repository, which triggers the fork event. For information about the REST API, see "Create a fork" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
fork n/a Last commit on default branch Default branch

For example, you can run a workflow when the fork event occurs.

on:
  fork

Gollum event: gollum

Runs your workflow when someone creates or updates a Wiki page, which triggers the gollum event.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
gollum n/a Last commit on default branch Default branch

For example, you can run a workflow when the gollum event occurs.

on:
  gollum

Issue comment event: issue_comment

Runs your workflow anytime the issue_comment event occurs. More than one activity type triggers this event. For information about the REST API, see "Issue comments" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
issue_comment - created
- edited
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when an issue comment has been created or deleted.

on:
  issue_comment:
    types: [created, deleted]

Issues event: issues

Runs your workflow anytime the issues event occurs. More than one activity type triggers this event. For information about the REST API, see "Issues" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
issues -opened
- edited
- deleted
- transferred
- pinned
- unpinned
- closed
- reopened
- assigned
- unassigned
- labeled
- unlabeled
- locked
- unlocked
- milestoned
- demilestoned
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when an issue has been opened, edited, or milestoned.

on:
  issues:
    types: [opened, edited, milestoned]

Label event: label

Runs your workflow anytime the label event occurs. More than one activity type triggers this event. For information about the REST API, see "Labels" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
label - created
- edited
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a label has been created or deleted.

on:
  label:
    types: [created, deleted]

Member event: member

Runs your workflow anytime the member event occurs. More than one activity type triggers this event. For information about the REST API, see "Collaborators" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
member - added
- edited
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a member has been added or deleted.

on:
  member:
    types: [added, deleted]

Milestone event: milestone

Runs your workflow anytime the milestone event occurs. More than one activity type triggers this event. For information about the REST API, see "Milestones" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
milestone - created
- closed
- opened
- edited
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a member has been opened or deleted.

on:
  milestone:
    types: [opened, deleted]

Page build event: page_build

Runs your workflow anytime someone pushes to a GitHub Pages-enabled branch, which triggers the page_build event. For information about the REST API, see "Pages" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
page_build n/a Last commit on default branch n/a

For example, you can run a workflow when the page_build event occurs.

on:
  page_build

Project event: project

Runs your workflow anytime the project event occurs. More than one activity type triggers this event. For information about the REST API, see "Projects" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
project - created
- updated
- closed
- reopened
- edited
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a project has been created or deleted.

on:
  project:
    types: [created, deleted]

Project card event: project_card

Runs your workflow anytime the project_card event occurs. More than one activity type triggers this event. For information about the REST API, see "Project cards" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
project_card - created
- moved
- converted to an issue
- edited
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a project card has been opened or deleted.

on:
  project_card:
    types: [opened, deleted]

Project column event: project_column

Runs your workflow anytime the project_column event occurs. More than one activity type triggers this event. For information about the REST API, see "Project columns" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
project_column - created
- updated
- moved
- deleted
Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a project column has been created or deleted.

on:
  project_column:
    types: [created, deleted]

Public event: public

Runs your workflow anytime someone makes a private repository public, which triggers the public event. For information about the REST API, see "Edit repositories" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
public n/a Last commit on default branch Default branch

For example, you can run a workflow when the public event occurs.

on:
  public

Pull request event: pull_request

Runs your workflow anytime the pull_request event occurs. More than one activity type triggers this event. For information about the REST API, see "Pull requests" in the GitHub Developer documentation.

Note: By default, a workflow only runs when a pull_request's activity type is opened, synchronize, or reopened. To trigger workflows for more activity types, use the types keyword.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
pull_request - assigned
- unassigned
- labeled
- unlabeled
- opened
- edited
- closed
- reopened
- synchronize
- ready_for_review
- locked
- unlocked
- review_requested
- review_request_removed
Last merge commit on the GITHUB_REF branch PR merge branch refs/pull/:prNumber/merge

You extend or limit the default activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."'

For example, you can run a workflow when a pull request has been assigned opened, synchronize or reopened.

on:
  pull_request:
    types: [assigned, opened, synchronize, reopened]
Pull request events for forked repositories

Note: Workflows do not run on private base repositories when you open a pull request from a forked repository.

When you create a pull request from a forked repository to the base repository, GitHub sends the pull_request event to the base repository and no pull request events occur on the forked repository.

Workflows don't run on forked repositories by default. You must enable GitHub Actions in the Actions tab of the forked repository.

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."

Pull request review event: pull_request_review

Runs your workflow anytime the pull_request_review event occurs. More than one activity type triggers this event. For information about the REST API, see "Pull request reviews" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
pull_request_review - submitted
- edited
- dismissed
Last merge commit on the GITHUB_REF branch PR merge branch refs/pull/:prNumber/merge

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a pull request review has been edited or dismissed.

on:
  pull_request_review:
    types: [edited, dismissed]
Pull request events for forked repositories

Note: Workflows do not run on private base repositories when you open a pull request from a forked repository.

When you create a pull request from a forked repository to the base repository, GitHub sends the pull_request event to the base repository and no pull request events occur on the forked repository.

Workflows don't run on forked repositories by default. You must enable GitHub Actions in the Actions tab of the forked repository.

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."

Pull request review comment event: pull_request_review_comment

Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the pull_request_review_comment event. More than one activity type triggers this event. For information about the REST API, see Review comments in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
pull_request_review_comment - created
- edited
- deleted
Last merge commit on the GITHUB_REF branch PR merge branch refs/pull/:prNumber/merge

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a pull request review comment has been created or deleted.

on:
  pull_request_review_comment:
    types: [created, deleted]
Pull request events for forked repositories

Note: Workflows do not run on private base repositories when you open a pull request from a forked repository.

When you create a pull request from a forked repository to the base repository, GitHub sends the pull_request event to the base repository and no pull request events occur on the forked repository.

Workflows don't run on forked repositories by default. You must enable GitHub Actions in the Actions tab of the forked repository.

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."

Push event: push

Note: The webhook payload available to GitHub Actions does not include the added, removed, and modified attributes in the commit object. You can retrieve the full commit object using the REST API. For more information, see "Get a single commit" in the GitHub Developer documentation".

Runs your workflow when someone pushes to a repository branch, which triggers the push event.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
push n/a Commit pushed, unless deleting a branch (when it's the default branch) Updated ref

For example, you can run a workflow when the push event occurs.

on:
  push

Release event: release

Note: The release event is not triggered for draft releases.

Runs your workflow anytime the release event occurs. More than one activity type triggers this event. For information about the REST API, see "Releases" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
release - published,
- unpublished
- created
- edited
- deleted
- prereleased
Last commit in the tagged release Tag of release

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when a release has been published.

on:
  release:
    types: [published]

Status event: status

Runs your workflow anytime the status of a Git commit changes, which triggers the status event. For information about the REST API, see Statuses in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
status n/a Last commit on default branch n/a

For example, you can run a workflow when the status event occurs.

on:
  status

Watch event: watch

Runs your workflow anytime the watch event occurs. More than one activity type triggers this event. For information about the REST API, see "Starring" in the GitHub Developer documentation.

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
watch - started Last commit on default branch Default branch

By default, all activity types trigger a workflow to run. You can limit your workflow runs to specific activity types using the types keyword. For more information, see "Workflow syntax for GitHub Actions."

For example, you can run a workflow when someone stars a repository, which is the started activity type that triggers the watch event.

on:
  watch
    types: [started]

Scheduled events: schedule

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
n/a n/a Last commit on default branch Default branch

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. The shortest interval you can run scheduled workflows is once every 5 minutes.

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: repository_dispatch

Webhook event payload Activity types GITHUB_SHA GITHUB_REF
repository_dispatch n/a Last commit on the GITHUB_REF branch Branch that received dispatch

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

This event does not have additional activity types so it does not support the types keyword.

on: repository_dispatch

Ask a human

Can't find what you're looking for?

Contact us