This page was generated based on Github’s Documentation. See our welcome page for context and details.
Github Event workflow_dispatch
#
Github Action Trigger #
Webhook event payload | Activity types | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
workflow_dispatch | Not applicable | Last commit on the GITHUB_REF branch or tag | Branch or tag that received dispatch |
Note: This event will only trigger a workflow run if the workflow file is on the default branch.
To enable a workflow to be triggered manually, you need to configure the workflow_dispatch
event. You can manually trigger a workflow run using the GitHub API, GitHub CLI, or GitHub browser interface. For more information, see “Manually running a workflow.”
on: workflow_dispatch
Providing inputs #
You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When you trigger the event, you can provide the ref
and any inputs
. When the workflow runs, you can access the input values in the inputs
context. For more information, see “Contexts.”
Notes:
- The workflow will also receive the inputs in the
github.event.inputs
context. The information in theinputs
context andgithub.event.inputs
context is identical except that theinputs
context preserves Boolean values as Booleans instead of converting them to strings. Thechoice
type resolves to a string and is a single selectable option. - The maximum number of top-level properties for
inputs
is 10. - The maximum payload for
inputs
is 65,535 characters.
This example defines inputs called logLevel
, tags
, and environment
. You pass values for these inputs to the workflow when you run it. This workflow then prints the values to the log, using the inputs.logLevel
, inputs.tags
, and inputs.environment
context properties.
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
type: choice
options:
- info
- warning
- debug
tags:
description: 'Test scenario tags'
required: false
type: boolean
environment:
description: 'Environment to run tests against'
type: environment
required: true
jobs:
log-the-inputs:
runs-on: ubuntu-latest
steps:
- run: |
echo "Log level: $LEVEL"
echo "Tags: $TAGS"
echo "Environment: $ENVIRONMENT"
env:
LEVEL: ${{ inputs.logLevel }}
TAGS: ${{ inputs.tags }}
ENVIRONMENT: ${{ inputs.environment }}
If you run this workflow from a browser you must enter values for the required inputs manually before the workflow will run.
You can also pass inputs when you run a workflow from a script, or by using GitHub CLI. For example:
gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=staging
For more information, see the GitHub CLI information in “Manually running a workflow.”
Event Payload #
This event occurs when a GitHub Actions workflow is manually triggered. For more information, see "Manually running a workflow."
For activity relating to workflow runs, use the workflow_run
event.
To subscribe to this event, a GitHub App must have at least read-level access for the "Contents" repository permission.
field | type | required | description |
---|---|---|---|
github.event.enterprise | object | optional | An enterprise on GitHub. Webhook payloads contain the |
github.event.inputs | object or null | required | |
github.event.installation | object | optional | The GitHub App installation. Webhook payloads contain the |
github.event.organization | object | optional | A GitHub organization. Webhook payloads contain the |
github.event.ref | string | required | |
github.event.repository | object | required | The repository on GitHub where the event occurred. Webhook payloads contain the |
github.event.sender | object | required | The GitHub user that triggered the event. This property is included in every webhook payload. |
github.event.workflow | string | required |