Forgejo · Codeberg · Gitea · Actions · workflow_dispatch · Checked October 28, 2026

Forgejo and Gitea: workflow dispatch refused

Starting a workflow by hand is POST /api/v1/repos/{owner}/{repo}/actions/workflows/{file name}/dispatches with a branch or tag in ref. The server looks up the ref, then the workflow file at that ref; Gitea also checks that the file has a workflow_dispatch trigger, Forgejo that the required inputs have values. The message names the step that failed. Forgejo answers these with 400, 403, 404 or 423, Gitea with 403, 404 or 422.

Gitea

Checked in 28.2.0, the latest release, of October 18, 2026 (routers/api/v1/repo/action.go, services/actions/workflow.go):

• 404 ref "v1.0" doesn't exist: no branch of that name. Gitea reads a name without refs/ as a branch only, so a tag has to be sent as refs/tags/v1.0; a branch can be sent as main or refs/heads/main.
• 404 workflow "deploy.yml" doesn't exist: no file of that name in the workflow folder of the commit the ref points at. The folder is the first of .gitea/workflows and .github/workflows that exists in that commit: once there is a .gitea/workflows folder, files in .github/workflows are not read (workflows.go; the list is the WORKFLOW_DIRS setting, actions.go).
• 422 workflow "deploy.yml" has no workflow_dispatch event trigger: the file at that ref has no workflow_dispatch under on:. The file is read at the ref you start it on, so a trigger added on another branch does not count until it is merged.
• 422 invalid workflow "deploy.yml": ...: the file does not parse; the rest of the message is the error of the parser.
• 422 ref is required parameter: the request has no ref.
• 403 workflow is disabled: someone disabled the workflow on the Actions page of the repository; enable it there.
• 403 user should have a permission to write to a repo: the account cannot write to Actions in this repository; the route asks for write access to the Actions unit (api.go).

Gitea does not refuse a missing input through the API: an input left out takes its default, or stays empty.

Forgejo

From its source (routers/api/v1/repo/action.go, services/actions/workflows.go):

• 400 could not expand reference 'v1.0': no tag, branch or commit of that name. Forgejo takes a plain name and looks for a tag first, then a branch, then a commit, so where a tag and a branch share a name, the tag wins; heads/main or refs/heads/main picks the branch (repo_ref.go).
• 400 reference 'refs/heads/release' does not exist: a full refs/ name was sent, and nothing is there.
• 404 workflow not found: no file of that name in the workflow folder at that ref, the first of .forgejo/workflows, .gitea/workflows and .github/workflows that exists (workflows.go).
• 400 input required for 'Environment': a required input with no default was left empty. The name is the description of the input, or its key when it has none.
• 400 ref is empty: the request has no ref.
• 403 user should have a permission to write to a repo: the account cannot write to Actions in this repository; the route asks for a token and write access to the Actions unit (api.go, req_repo_writer.go).
• 423, a message ending in is archived: the repository is archived (must_not_be_archived.go).

When it works

Both answer 204 with no body. Forgejo answers 201 with the run (id, run_number, jobs) when the request has "return_run_info": true; Gitea answers 200 with workflow_run_id and html_url when the address ends in ?return_run_details=true.

Forgejo and Gitea Actions in IntelliJ IDEA

Pipeline Inbox for Forgejo and Gitea, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, has Run Workflow: it lists only the workflows that have workflow_dispatch at the branch or tag you pick, read from the same folders as the server, with a field for each input the file declares. When the server refuses, the dialog stays open with the message of the server. The runs, jobs and logs are free; re-running, cancelling and starting workflows are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Forgejo, Gitea and Codeberg are names of their respective owners; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by the Forgejo project, Codeberg e.V., the Gitea project or JetBrains.

More: "No matching online runner with label" · Gitea Actions API "token is required" · Job log expired · Forgejo Actions and Gitea Actions in JetBrains IDEs · 日本語