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



NAME
       gt-workflow-run - Dispatch a workflow



SYNOPSIS
       gt workflow run <workflow> [flags]



DESCRIPTION
       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.


   ARGUMENTS
       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").


   JSON FIELDS
       id, url



OPTIONS
       --dry-run[=false]   Show the write requests gt would send, without
       sending them


       -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



OPTIONS INHERITED FROM PARENT COMMANDS
       --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)


       --template=""  Format JSON output using a Go template; implies --json
       (see gt help formatting)


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



EXAMPLE
       # 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



SEE ALSO
       gt-workflow(1)

gitea-cli                          Nov 2026                 GT-WORKFLOW-RUN(1)