About workflows

Aworkflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.

Workflows are defined in the.github/workflows directory in a repository. A repository can have multiple workflows, each of which can perform a different set of tasks such as:

• Building and testing pull requests
• Deploying your application every time a release is created
• Adding a label whenever a new issue is opened

Workflow basics

A workflow must contain the following basic components:

1. One or moreevents that will trigger the workflow.
2. One or morejobs, each of which will execute on arunner machine and run a series of one or moresteps.
3. Each step can either run a script that you define or run an action, which is a reusable extension that can simplify your workflow.

For more information on these basic components, seeUnderstanding GitHub Actions.

Workflow triggers

Workflow triggers are events that cause a workflow to run. These events can be:

• Events that occur in your workflow's repository
• Events that occur outside of GitHub and trigger arepository_dispatch event on GitHub
• Scheduled times
• Manual

For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened.

Workflow triggers are defined with theon key. For more information, seeWorkflow syntax for GitHub Actions.

The following steps occur to trigger a workflow run:

1. An event occurs on your repository. The event has an associated commit SHA and Git ref.
2. GitHub searches the.github/workflows directory in the root of your repository for workflow files that are present in the associated commit SHA or Git ref of the event.
3. A workflow run is triggered for any workflows that haveon: values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run.

Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, GitHub sets theGITHUB_SHA (commit SHA) andGITHUB_REF (Git ref) environment variables in the runner environment. For more information, seeStore information in variables.

For more information, seeTriggering a workflow.

Next steps

To build your first workflow, seeCreating an example workflow.