---
title: Gitea Actions
description: Monitoring of Gitea Actions workflows in Pipedash on a self-hosted Gitea instance, with workflow dispatch and run cancel.
---

The Gitea Actions plugin (`gitea`) monitors the workflows of the selected repositories on a Gitea instance. It shows the latest run of each workflow, loads run history, dispatches workflows and cancels runs.

## Requirements

Pipedash needs Gitea 1.24 or newer. That version added the `/actions/runs` endpoint the plugin reads runs from. Cancel uses the `/actions/runs/{id}/cancel` endpoint, which newer Gitea releases add. On a Gitea without it, Pipedash reports `Run cancellation is not available on this Gitea version`.

The plugin authenticates with an access token. Create it in Gitea under Settings, Applications.

| Scope | Required | What it unlocks |
|---|---|---|
| `read:user` | Yes | Credential validation and the repository list of the token owner |
| `read:organization` | No | Filtering repositories by organization. Without it, the picker only shows the token owner. |
| `read:repository` | Yes | Workflow listing, run history and status monitoring |
| `write:repository` | No | Workflow dispatch and cancel. Without it, Pipedash is read-only. |

## Configuration

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `base_url` | Text | Yes | None | URL of the Gitea instance, for example `https://gitea.example.com`. |
| `token` | Password | Yes | None | Gitea access token with the scopes above. |

One more key goes in the config table of the TOML file:

- `selected_items`: Comma-separated `owner/repo` names to monitor.

## Base URL

Gitea has no hosted default, so `base_url` is required. Pipedash appends `/api/v1`. A trailing slash is ignored.

## Pipeline discovery

Discovery lists the repositories the token owner owns or contributes to. The picker browses by organization or by the token owner and searches by repository name. For each selected repository, Pipedash lists the workflow files under `.gitea/workflows` and shows the latest run of each workflow. A repository that fails to load fails the refresh and keeps the cached workflows of the provider. An empty `selected_items` shows the error `No repositories configured`.

Gitea 1.24 to 1.26 have no endpoint that lists runs per workflow, so Pipedash reads the repository run list newest first and keeps the runs of the requested workflow. It reads at most 10 pages of 50 runs. A workflow whose newest run is older than that shows as `pending` with no run history.

## Trigger parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `ref` | String | Yes | `main` | Branch, tag or commit SHA to run the workflow on. |

Pipedash reads the workflow file and adds one parameter per `workflow_dispatch` input, in file order, with its `type` (`string`, `boolean`, `choice` or `number`), `default`, `description` and `required` flag. The form labels each one with the input name. Every input goes to Gitea as a workflow `inputs` value in the dispatch request, so a workflow input called `ref` stays separate from the branch field. Pipedash sends the dispatch request once and does not retry it, so one click starts at most one run.

## Cancel

Pipedash looks the run up by its run number and cancels it through the Gitea API. This needs the `write:repository` scope and a Gitea release with the cancel endpoint.

## TOML example

```toml
[providers.gitea-home]
name = "Gitea Home"
type = "gitea"
token = "${GITEA_TOKEN}"
refresh_interval = 30

[providers.gitea-home.config]
base_url = "https://gitea.example.com"
selected_items = "acme/platform,acme/web"
```

## Status mapping

Gitea reports runs with the same `status` and `conclusion` pair as GitHub.

| Pipedash status | Gitea state |
|---|---|
| `success` | `completed` with conclusion `success` |
| `failed` | `completed` with conclusion `failure` |
| `running` | `in_progress` or `queued` |
| `pending` | Any other combination, for example `waiting` |
| `cancelled` | `completed` with conclusion `cancelled` |
| `skipped` | `completed` with conclusion `skipped` |

Runs that have not started yet carry no timestamps in Gitea 1.26, so Pipedash shows the time it read the run as the start time until the run starts.