GT-WORKFLOW-RUN(1) gitea-cli Manual GT-WORKFLOW-RUN(1)

gt-workflow-run - Dispatch a workflow

gt workflow run <workflow> [flags]

Start a run of a workflow that has a workflow_dispatch trigger.

Inputs are checked against the inputs that the workflow declares: unknown inputs, missing required inputs and values that a choice, boolean or number input does not accept are refused. In a terminal, gt asks for missing required inputs, or for every input when none is given.

The workflow is looked up, like Gitea does, among the files in the first of .gitea/workflows and .github/workflows that exists on the branch or tag it runs on, so one that exists only on a branch runs with --ref. gt workflow list shows those of the default branch.

Without --ref, the workflow runs on the checked-out branch, which must be on the server, or on the default branch when the repository does not come from the working directory.

With --follow, the command exits with 5, like gt run watch, when the run completes without success, and with 3 when --timeout expires first.

A workflow can be supplied as its file name ("ci.yml"), its file name without
extension ("ci"), its path (".gitea/workflows/ci.yml") or its name ("CI").

id, url

-f, --field=[] Workflow input as key=value (repeatable)

--follow[=false] Follow the logs of the run's jobs after dispatching it

-h, --help[=false] help for run

-i, --interval=2s Polling interval with --follow

-r, --ref="" Branch or tag to run the workflow on (default: the current or default branch)

--timeout=30m0s Maximum time to follow

--csv[=""] Output CSV with the specified comma-separated fields, or all fields

--cwd="" Working directory for repository discovery

--debug[=false] Log the method, URL, status, and duration of each HTTP request to stderr

--host="" Gitea instance URL, including any base path

--interactive[=false] Allow prompts with machine output

-q, --jq="" Filter JSON output using a jq expression; implies --json

--json[=""] Output JSON with the specified comma-separated fields, or all fields

--no-input[=false] Disable prompts and implicit editor/browser interactions

--remote="" Git remote used for repository discovery

-R, --repo="" Select a repository as OWNER/REPO or URL

--sudo="" Perform API requests as this user (requires an administrator account)

--user="" Account name on the selected instance

# run a workflow on the default or current branch
$ gt workflow run CI
# run it on a branch with inputs
$ gt workflow run ci.yml --ref main -f target=production -f dry_run=false
# run it and follow the logs of its jobs
$ gt workflow run nightly --follow

gt-workflow(1)

Nov 2026 gitea-cli