Add project workflow feature so users can define how to execute steps when project related events fired

[lunny]

This PR introduces project workflows, allowing users to configure event-based automations directly from the UI.
Users can define filters and actions for each workflow event, and duplicate existing events when needed.

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.

Available Events

Currently, the following nine events are supported:

• On issues/pull requests opened
• On issues/pull requests closed
• On issues/pull requests reopened
• On issues/pull requests was added to the project
• On issues/pull requests was removed to the project
• On issues/pull requests' column was changed
• On code changes requested
• On code review approved
• On pull request merged

Each event type supports its own set of filters and actions.

Available Filters

There are four types of filters that can be configured for an 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.

Available Actions

There are four types of actions that can be executed when an event is triggered:

• 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.

Enable/Disable an event workflow

Each event workflow can be individually enabled or disabled. When disabled, the workflow will be ignored even if the event occurs. This feature is useful when you want to temporarily stop certain automated actions without deleting the workflow configuration.

Clone an event workflow

When you need multiple workflows for the same event, you can clone an existing event to create a new one with different filters and actions. This allows you to customize how the same event behaves under different conditions, making workflows more flexible and powerful.

Screen shots

• View mode

• Edit mode

• Dark theme

• Resolve [Feature] Add automated project board #14359
• Resolve Allow kanban/project board to set labels on column switch #26704
• Resolve [Feature] Kanban automation using labels #27990
• Replace add/remove label on kanban column change #28745

Documentation PR https://gitea.com/gitea/docs/pulls/308

[lunny]

I'm now hesitate to add this feature because looks like some actions can do the same things. Like https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions and more third-party actions can do it easier.

[rohrschacht]

I would really like to see this merged, I am waiting for the ability to automatically set a project for a new issue via the issue template (#25028). GitHub provides this through an "org-name/BOARD_ID" syntax as announced here. I think having to set up an action for that (which would also require to set up a runner?) is quite cumbersome for such a simple feature.

[silkentrance]

I'm now hesitate to add this feature because looks like some actions can do the same things. Like https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions and more third-party actions can do it easier.

@lunny

I do not know, but firing up multiple containers to just set a specific label or remove a label, or even re-open or close an issue as part of the workflow seems to be overkill to me, what do you think?

[thekk1]

I'm now hesitate to add this feature because looks like some actions can do the same things. Like https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions and more third-party actions can do it easier.

What's the status here now? This is quite a wanted feature.
Do you have just a feeling about this or a specific good reason?
Running multiple containers for just moving around a Issue is for sure not the best practice.

[lunny]

I'm now hesitate to add this feature because looks like some actions can do the same things. Like https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions and more third-party actions can do it easier.

What's the status here now? This is quite a wanted feature. Do you have just a feeling about this or a specific good reason? Running multiple containers for just moving around a Issue is for sure not the best practice.

Yes, this is a good reason to use the internal implementation rather than CI/CD. I will continue this work.

[thekk1]

I'm now hesitate to add this feature because looks like some actions can do the same things. Like https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions and more third-party actions can do it easier.

What's the status here now? This is quite a wanted feature. Do you have just a feeling about this or a specific good reason? Running multiple containers for just moving around a Issue is for sure not the best practice.

Yes, this is a good reason to use the internal implementation rather than CI/CD. I will continue this work.

Great, thx for your feedback. I am really looking forward to it.

[thekk1]

As far as I understand the description, this will depend on Workflows?
So Actions has to be enabled?
This would be a problem for us, because the workflows in our repos are for the environment of our customers and Actions are always disabled because they will not work in our environment.

[lunny]

As far as I understand the description, this will depend on Workflows? So Actions has to be enabled? This would be a problem for us, because the workflows in our repos are for the environment of our customers and Actions are always disabled because they will not work in our environment.

No. This is project workflow which is different from Actions workflow.

[lunny]

And what's better? Storing the workflows in the special YAML files on the default branch or storing them in the database? This is a block to prevent me from continuing the work.

[thekk1]

I would purpose to store them in the database. Branches are for code changes and depending stuff but this is a projekt management feature that is specific for gitea. i.e.: If you mirror your code to an other git system like github the projekt workflows are only garbage there.

[eeyrjmr]

I would purpose to store them in the database. Branches are for code changes and depending stuff but this is a projekt management feature that is specific for gitea. i.e.: If you mirror your code to an other git system like github the projekt workflows are only garbage there.

but storing in the db will require some form of UI to create/edit.
Right now .gitea/* is used to store issue templates and all of that is "garbage" if you were to mirror into github since github only looks in .github thus that objection is moot.

[thekk1]

but storing in the db will require some form of UI to create/edit. Right now .gitea/* is used to store issue templates and all of that is "garbage" if you were to mirror into github since github only looks in .github thus that objection is moot.

For my defence I didn't know about the templates and the storage path. In that case I would agree to that argument.

[Woonhyung59]

Thank you for working on this important feature. Many users, including myself, are eagerly anticipating the addition of project workflows to Gitea. This functionality would greatly enhance project management capabilities within the platform.

[wxiaoguang]

Does it need a general "gitea system account user" for more similar cases?

[lunny]

It may be better to use different system bot account IDs for different features, so we can clearly identify which actions come from which subsystem and assign appropriate permissions to each bot account.

Using a single, general system account does reduce code complexity and maintenance overhead. However, adding an additional system account does not seem to require much effort, and it is not a frequent operation. Given the benefits in clarity and permission isolation, using separate system accounts for different features may be the better approach.

[wxiaoguang]

You are just keeping adding "breaking changes" to tell end users that "if you have a user named 'project-workflow', you need to rename it before upgrade", and then "if you have a user named 'xxxx' ...", "if you have a user named 'yyyy' ... "

And you just keep forgetting adding the new names to reservedUsernames

[lunny]

I think we can also remove those reserved names. A bot account should not have a profile and have a bot label which is different from a normal account. i.e. This is an bot account from Github, it will be point to a /apps/xxxx but not a normal profile. And there is a bot label near the name.

[wxiaoguang]

I think we can also remove those reserved names. A bot account should not have a profile and have a bot label which is different from a normal account. i.e. This is an bot account from Github, it will be point to a /apps/xxxx but not a normal profile. And there is a bot label near the name.

How does it answer the question? What if the end user already has a user named "project-workflow" in their instance?

[lunny]

It will not conflict at the moment. The original user could be visited still and the bot account will be displayed "project-workflow" with a following bot label. Even if it may confuse users, but it will not affect the original user. The issue is related how to handle different user types which should have a complete solution in another PR.

[wxiaoguang]

Maybe "at the moment"

OK, that's your choice to keep introducing fragile designs and confusing end users. If you believe it's right, I won't block.

[wxiaoguang]

By the way, I don't believe you are able to figure out "how to handle different user types which should have a complete solution in another PR"

There are still buggy designs or patches unresolved, for example:

• Add new user types reserved, bot, and remote #24026 (comment)
• Allow admin to change user's type #33758 (review)
• Need a complete fix for broken GetUserByName #36208

Already a mess, just keep making the whole system more messy.

[wxiaoguang]

It seems to be a bad name and is likely to conflict with end user's name.

[lunny]

All system bot type user have a [bot] prefix before the name and it should have no profile page. Then it's different from the user who have the same name.

[tpokorra]

@lunny can I support you in any way to fix the issues that came up in the review?

[lunny]

@lunny can I support you in any way to fix the issues that came up in the review?

Yes, please send PRs to my fork repository.