gitea-docs/docs/usage/projects/project-workflows.md

date, slug, sidebar_position, description

date	slug	sidebar_position	description
2025-11-25T18:58:22Z	project-workflows	1	Automate tasks on repository projects by reacting to events with filters and actions.

Project Workflows

Project workflows let you automate what happens on a repository project board whenever an issue or pull request triggers a supported event. The feature runs entirely inside Gitea, so no external runners or webhooks are required.

Users who can edit the project (repository owners, maintainers, and project managers) may create, edit, clone, enable, or disable workflows from the project UI.

Open the workflow editor

1. Navigate to the repository → Projects and open the board you want to automate.
2. Select the Workflows tab that appears next to the project columns.
3. Click left sidbar to edit an event definition.
4. Choose the event, add any filters, chain the actions you need, and save.

Every workflow lives inside the project it belongs to. If you need similar logic for another project, recreate or clone the workflow in that project.

Concepts

Every workflow is composed of event, filters, and actions.

• Event - An Event defines when a workflow should be triggered. It represents specific activities such as an issue being opened, a pull request being merged, or a project column being changed.
• Filter - A Filter refines when an event should take effect. It allows users to specify conditions like issue type, labels, or project columns to ensure actions only run in targeted scenarios.
• Action - An Action defines what happens when the event and filters match. It performs operations such as adding labels, moving issues between columns, or changing the issue or pull request state.

Supported events

Event	Fires when
Issues/PRs opened	A new issue or pull request is created.
Issues/PRs closed	The issue or pull request is closed.
Issues/PRs reopened	A previously closed issue or pull request is reopened.
Added to project	An issue or pull request is added to the project.
Removed from project	An issue or pull request is removed from the project.
Column changed	A card moves from one column to another.
Code changes requested	A reviewer requests changes on a pull request connected to the project.
Code review approved	A reviewer approves the pull request.
Pull request merged	The pull request is merged.

Each event can have multiple workflows so you can handle the same trigger differently for separate sets of cards.

Filters

Filters refine when an event should run. If none are configured, the workflow runs on every occurrence of the event.

• Apply to - Specify the target type: issues only, pull requests only, or issues and pull requests.
• Labels - Trigger the event only if the issue or pull request contains one or more specified labels.
• Move from column - Filter events based on the original project column.
• Move to column - Filter events based on the destination project column.

You can combine filters to require multiple conditions (for example, PRs with the needs-review label moving into the "Review" column).

Actions

Workflows execute their actions in the order you add them. Available actions are:

• Add labels - Automatically add one or more labels to the issue or pull request.
• Remove labels - Remove one or more specified labels.
• Move to column - Move the issue or pull request to a designated project column.
• Issue state - Change the state by closing or reopening the issue or pull request.

Combine actions to build more complex automations (for example, move the card and apply labels in a single workflow).

Managing workflows

Enable or disable

Each workflow has its own toggle. Disable a workflow to pause it temporarily without losing its configuration. Disabled workflows are ignored even if the event fires.

Clone an event workflow

Use Clone to duplicate the current workflow (event, filters, and actions). This is useful when you need several variations of the same trigger—adjust the copied filters/actions and save under a new name.

Example: triage incoming bug reports

The following workflow keeps bug reports organized automatically:

1. Event: Issues/PRs opened.
2. Filters: Apply to issues only; Labels include bug.
3. Actions:
   • Add labels → needs-triage.
   • Move to column → "Needs Triage".
   • Issue state → leave open (no change) but could optionally reopen to ensure visibility.

With this configuration every new bug issue when added to this project immediately lands in the right column with the correct label, so maintainers always know what still needs triage.

Start small, test the workflow on a single project, and expand the automation set as your team discovers repetitive tasks you can offload to workflows.