mirror of
https://gitea.com/gitea/docs.git
synced 2026-06-24 13:15:55 +00:00
93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
---
|
|
date: "2025-11-25T18:58:22Z"
|
|
slug: "project-workflows"
|
|
sidebar_position: 1
|
|
description: "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.
|