Workflow syntax for GitHub Actions - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Workflow syntax for GitHub Actions A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration. In this article About YAML syntax for workflows Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. If you're new to YAML and want to learn more, see Learn YAML in Y minutes .
You must store workflow files in the .github/workflows directory of your repository. Tip Unlike traditional GitHub Actions workflows that require you to script every decision as YAML job steps, GitHub Agentic Workflows use YAML frontmatter for triggers and configuration, but let you describe what you want in natural-language Markdown—so you don't need to anticipate and encode every scenario in advance. For more information, see Creating GitHub Agentic Workflows . name The name of the workflow.
GitHub displays the names of your workflows under your repository's "Actions" tab. If you omit name , GitHub displays the workflow file path relative to the root of the repository. run-name The name for workflow runs generated from the workflow. GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If run-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run.
For example, for a workflow triggered by a push or pull_request event, it is set as the commit message or the title of the pull request. This value can include expressions and can reference the github and inputs contexts. Example of run-name run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }} on To automatically trigger a workflow, use on to define which events can cause the workflow to run. For a list of available events, see Events that trigger workflows .
You can define single or multiple events that can trigger a workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. These options are described in the following sections. Using a single event For example, a workflow with the following on value will run when a push is made to any branch in the workflow's repository: on: push Using multiple events You can specify a single event or multiple events.
For example, a workflow with the following on value will run when a push is made to any branch in the repository or when someone forks the repository: on: [ push , fork ] If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered. Using activity types Some events have activity types that give you more control over when your workflow should run.
Use on.<event_name>.types to define the type of event activity that will trigger a workflow run. For example, the issue_comment event has the created , edited , and deleted activity types. If your workflow triggers on the label event, it will run whenever a label is created, edited, or deleted. If you specify the created activity type for the label event, your workflow will run when a label is created but not when a label is edited or deleted. on: label: types: - created If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow.
If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events. on: issues: types: - opened - labeled For more information about each event and their activity types, see Events that trigger workflows .
Using filters Some events have filters that give you more control over when your workflow should run. For example, the push event has a branches filter that causes your workflow to run only when a push to a branch that matches the branches filter occurs, instead of when any push occurs. on: push: branches: - main - 'releases/**' Using activity types and filters with multiple events If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately.
You must append a colon ( : ) to all events, including events without configuration. For example, a workflow with the following on value will run when: A label is created A push is made to the main branch in the repository A push is made to a GitHub Pages-enabled branch on: label: types: - created push: branches: - main page_build: on.<event_name>.types Use on.<event_name>.types to define the type of activity that will trigger a workflow run.
Most GitHub events are triggered by more than one type of activity. For example, the label is triggered when a label is created , edited , or deleted . The types keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a webhook event, the types keyword is unnecessary. You can use an array of event types . For more information about each event and their activity types, see Events that trigger workflows . on: label: types: [ created , edited ] on.<pull_request|pull_request_target>.<branches|branches-ignore> When using the pull_request and pull_request_target events, you can configure a workflow to run only for pull requests that target specific branches.
Use the branches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore filter when you only want to exclude branch name patterns. You cannot use both the branches and branches-ignore filters for the same event in a workflow. If you define both branches / branches-ignore and paths / paths-ignore , the workflow will only run when both filters are satisfied.
The branches and branches-ignore keywords accept glob patterns that use characters like * , ** , + , ? , ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \ . For more information about glob patterns, see the Workflow syntax for GitHub Actions . Example: Including branches The patterns defined in branches are evaluated against the Git ref's name.
For example, the following workflow would run whenever there is a pull_request event for a pull request targeting: A branch named main ( refs/heads/main ) A branch named mona/octocat ( refs/heads/mona/octocat ) A branch whose name starts with releases/ , like releases/10 ( refs/heads/releases/10 ) on: pull_request: # Sequence of patterns matched against refs/heads branches: - main - 'mona/octocat' - 'releases/**' If a workflow is skipped due to branch filtering, path filtering , or a commit message , then checks associated with that workflow will remain in a "Pending" state.
A pull request that requires those checks to be successful will be blocked from merging. Example: Excluding branches When a pattern matches the branches-ignore pattern, the workflow will not run. The patterns defined in branches-ignore are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event unless the pull request is targeting: A branch named mona/octocat ( refs/heads/mona/octocat ) A branch whose name matches releases/**-alpha , like releases/beta/3-alpha ( refs/heads/releases/beta/3-alpha ) on: pull_request: # Sequence of patterns matched against refs/heads branches-ignore: - 'mona/octocat' - 'releases/**-alpha' Example: Including and excluding branches You cannot use branches and branches-ignore to filter the same event in a sing
The rest of this page is on the live site.