Forgejo Workflow Dispatch — Action

Trigger a workflow workflow_dispatch event on Forgejo (same repo, another repo on the same instance, or a different Forgejo instance). This action calls the Forgejo API endpoint that creates a workflow_dispatch event so your workflows can be started programmatically.

Note

If you can, prefer workflow_call (reusable workflows) for tightly-coupled workflow chaining — it’s often safer and easier to reason about than ad-hoc dispatching across repos.

Quick start

- name: Dispatch workflow in same repo
  uses: https://git.michaelsasser.org/actions/workflow-dispatch@main
  with:
    workflowname: test.yml
    token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

Inputs

Name	Required	Type	Default	Description
server_url	no	string	instance default	Base URL of the Forgejo instance (e.g. https://forgejo.example.org). If omitted the action will attempt to use the instance the runner/workflow is running on — but explicitly set it when targeting a different Forgejo instance.
repository	no	string	current repository	Target repository in owner/name form (e.g. michael/foobar). Omit to dispatch in the current repository.
workflowname	yes	string	—	The workflow file path (filename) inside .forgejo/workflows/, e.g. demo.yml or deploy/main.yml.
workflowref	no	string	refs/heads/main	The git ref to run the workflow on — a branch or tag (e.g. refs/heads/main or main). Best practice: pass this explicitly.
token	yes	secret/string	—	Personal access token used to authenticate to the Forgejo API. Store in a secret and never print it. The token must have repository write permissions.

SECURITY: Use ${{ secrets.MY_TOKEN }} rather than embedding plaintext tokens.

Example usages

1) Dispatch a workflow in the same repository (default instance & repo)

- name: Dispatch same-repo workflow
  uses: https://git.michaelsasser.org/actions/workflow-dispatch@main
  with:
    workflowname: test.yml
    token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

2) Dispatch a workflow in another repository on the same Forgejo instance

- name: Dispatch other-repo workflow
  uses: https://git.michaelsasser.org/actions/workflow-dispatch@main
  with:
    repository: michael/foobar
    workflowname: foo.yml
    token: ${{ secrets.OTHER_PERSONAL_ACCESS_TOKEN }}

3) Dispatch on a different Forgejo instance and branch

- name: Dispatch remote-instance workflow on master
  uses: https://git.michaelsasser.org/actions/workflow-dispatch@main
  with:
    server_url: https://forgejo.another-instance.com
    repository: michael/baz
    workflowref: refs/heads/master
    workflowname: bar.yml
    token: ${{ secrets.REMOTE_PERSONAL_ACCESS_TOKEN }}

Requirements

• Make your workflow explicitly accept workflow_dispatch (example: on: workflow_dispatch:).
• Always store tokens as repository/organization secrets and grant the smallest scope required. On Forgejo that typically means write:repository.
• Prefer passing an explicit workflowref (branch or tag).

Troubleshooting

• 401 / 403 (Unauthorized / Forbidden) — Token missing or insufficient scope. Ensure the PAT is set as a secret and has repository write permissions for the target repo.
• 404 (Not Found) — Wrong server_url, repository or workflowname; or the token cannot see the repository (permissions). Double-check the path: .forgejo/workflows/<workflowname> exists.
• 422 / Bad request — API expects ref and/or inputs in a certain format. Ensure workflowref maps to an existing branch/tag and that inputs match the workflow’s on.workflow_dispatch.inputs schema.

License

Copyright © 2025 Michael Sasser info@michaelsasser.org. Released under the MIT license.