Start a workflow by hand

Run one workflow file now, at a branch or tag you choose, with inputs.

Last updated 18 November 2026View as Markdown

The file must accept a manual start: a GitHub-syntax file under .github/workflows/ with on: workflow_dispatch, or a native file with a manual trigger under on:. The file is read at the tip of the ref you name, so what runs is what that branch or tag holds now.

Replace repo-id with the repository's id.

Prerequisites

  • ci:StartWorkflow on the repository (rn:ews::<organization id>:ci:repository/<repository id>).
  • The run is started as you: the secrets its jobs get are checked against your secrets:GetSecretValue (see Give a job a secret).

Start the workflow

Not available in Console. The console has no button to start a workflow by hand.

ref is a branch or a tag, by name or as a full ref (refs/tags/v1.2.0); a name that is no branch is tried as a tag. Without ref, the default branch is used. Inputs you leave out take the defaults the workflow declares.

Result

201 with { runId, workflowName, path }; the run is queued with the trigger manual.

For a GitHub-syntax file, inputs are checked against its workflow_dispatch inputs before the run exists:

  • 400 "Unexpected inputs provided: …"
  • 400 "Required input 'channel' not provided"
  • 400 "Input 'dry-run' must be true or false", "… must be a number", "… must be one of: …", "… is not a valid environment name"

Other refusals:

  • 400 "Invalid ref"; 404 "No such branch or tag: …".
  • 404 ".github/workflows/release.yml is not a workflow file at main".
  • 400 "Workflow is invalid: …" when the file does not parse.
  • 409 "… did not start: … It needs on: workflow_dispatch (or on.manual in our format)" when the file does not accept a manual start.
Did this page help you?