Skip to content
forgit api docs

Create a workflow dispatch event

POST
/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches

You can use this endpoint to manually trigger a GitHub Actions workflow run. You can replace workflow_id with the workflow file name. For example, you could use main.yaml.

You must configure your GitHub Actions workflow to run when the workflow_dispatch webhook event occurs. The inputs are configured in the workflow file. For more information about how to configure the workflow_dispatch event in the workflow file, see “Events that trigger workflows.”

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

workflow_id
required
One of:
integer

The ID of the workflow. You can also pass the workflow file name as a string.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
ref
required

The git reference for the workflow. The reference can be a branch or tag name.

string
inputs

Input keys and values configured in the workflow file. The maximum number of properties is 25. Any default properties configured in the workflow file will be used when inputs are omitted.

object
<= 25 properties
key
additional properties
any
return_run_details

Whether the response should include the workflow run ID and URLs.

boolean
Examples
Example default 
{
  "ref": "topic-branch",
  "inputs": {
    "name": "Mona the Octocat",
    "home": "San Francisco, CA"
  }
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response including the workflow run ID and URLs when return_run_details parameter is true.

Media type application/json
Workflow Dispatch Response

Response containing the workflow run ID and URLs.

object
workflow_run_id
required
Workflow Run ID

The ID of the workflow run.

integer format: int64
run_url
required

The URL to the workflow run.

string format: uri
html_url
required
string format: uri
Examples
Example default 
{
  "workflow_run_id": 1,
  "run_url": "https://api.github.com/repos/octo-org/octo-repo/actions/runs/1",
  "html_url": "https://github.com/octo-org/octo-repo/actions/runs/1"
}

204

Section titled “ 204 ”

Empty response when return_run_details parameter is false.