Archived
Add OpenProject Gitea integration plugin
Implements a Gitea integration for OpenProject following the same patterns as the bundled GitHub and GitLab integrations. - Webhook endpoint at /webhooks/gitea with HMAC-SHA256 verification - Handles pull_request and issue_comment events - Links Gitea PRs to work packages via OP# references or URLs - Posts journal comments on WPs for PR lifecycle events - Gitea tab on the work package split view - V3 API endpoint: GET /api/v3/work_packages/:id/gitea_pull_requests - Admin settings UI for bot user and webhook secret - Nightly cron job to clean up unlinked PR records
This commit is contained in:
45 files changed
+2561
No files matched your search
@@ -0,0 +1,189 @@
|
||||
# OpenProject Gitea Integration
|
||||
|
||||
An OpenProject module that integrates [Gitea](https://gitea.com) pull requests with OpenProject work packages — following the same patterns as the bundled GitHub and GitLab integrations.
|
||||
|
||||
## Overview
|
||||
|
||||
When a pull request in Gitea references an OpenProject work package (via a URL or `OP#<id>`), this plugin:
|
||||
|
||||
- Records the pull request in OpenProject and links it to the work package
|
||||
- Posts automated journal comments on the work package when the PR is opened, merged, closed, or reopened
|
||||
- Shows a **Gitea** tab on the work package split-view listing all linked pull requests with their state and labels
|
||||
- Reacts to PR comments that mention a work package
|
||||
|
||||
## Supported webhook events
|
||||
|
||||
| Gitea event | Effect in OpenProject |
|
||||
|---|---|
|
||||
| `pull_request` — opened | Links PR to work package; posts "PR Opened" comment |
|
||||
| `pull_request` — closed (not merged) | Updates PR state; posts "PR Closed" comment |
|
||||
| `pull_request` — closed (merged) | Updates PR state to merged; posts "PR Merged" comment |
|
||||
| `pull_request` — reopened | Updates PR state; posts "PR Reopened" comment |
|
||||
| `pull_request` — edited / synchronized | Updates the stored PR record (no comment) |
|
||||
| `issue_comment` — created | Posts a comment on any work package referenced in the comment body |
|
||||
|
||||
## Referencing work packages
|
||||
|
||||
In a pull request title, description, or comment, reference a work package using:
|
||||
|
||||
- A full URL: `https://openproject.example.com/work_packages/42`
|
||||
- A short reference: `OP#42` or `OP#PROJ-42`
|
||||
|
||||
Multiple references in the same text are all picked up.
|
||||
|
||||
## Requirements
|
||||
|
||||
- OpenProject ≥ 13
|
||||
- Ruby 3.4+
|
||||
- The `openproject-webhooks` gem (bundled with OpenProject)
|
||||
|
||||
## Installation
|
||||
|
||||
### Packaged (DEB/RPM) installation
|
||||
|
||||
Create a custom Gemfile (e.g. `/etc/openproject/Gemfile.custom`):
|
||||
|
||||
```ruby
|
||||
group :opf_plugins do
|
||||
gem 'openproject-gitea_integration', '~> 1.0'
|
||||
end
|
||||
```
|
||||
|
||||
Tell OpenProject to use it and trigger a recompile of frontend assets:
|
||||
|
||||
```shell
|
||||
openproject config:set CUSTOM_PLUGIN_GEMFILE=/etc/openproject/Gemfile.custom
|
||||
openproject config:set RECOMPILE_ANGULAR_ASSETS=true
|
||||
sudo openproject configure
|
||||
```
|
||||
|
||||
### Docker installation
|
||||
|
||||
Follow the [OpenProject Docker plugin guide](https://www.openproject.org/docs/installation-and-operations/installation/docker/#openproject-plugins). Add the gem to your custom Gemfile and rebuild the image.
|
||||
|
||||
### Manual / monorepo installation
|
||||
|
||||
1. Clone this repository next to your OpenProject checkout, or place it at `modules/gitea_integration/` inside the OpenProject source tree.
|
||||
|
||||
2. Add the gem to your `Gemfile.plugins` (or `Gemfile.modules`):
|
||||
|
||||
```ruby
|
||||
group :opf_plugins do
|
||||
# from RubyGems:
|
||||
gem 'openproject-gitea_integration', '~> 1.0'
|
||||
# or from a local path:
|
||||
# gem 'openproject-gitea_integration', path: 'modules/gitea_integration'
|
||||
end
|
||||
```
|
||||
|
||||
3. Install dependencies:
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
```
|
||||
|
||||
4. Run the database migration:
|
||||
|
||||
```bash
|
||||
bundle exec rails db:migrate
|
||||
```
|
||||
|
||||
5. Rebuild the frontend:
|
||||
|
||||
```bash
|
||||
cd frontend && npm ci && npm run build
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### 1. Create a bot user in OpenProject
|
||||
|
||||
Create a dedicated OpenProject user that will post automated comments on work packages. Add this user to every project where you want the integration to be active, with a role that allows:
|
||||
|
||||
- Viewing work packages
|
||||
- Adding work package comments
|
||||
|
||||
Generate an **API token** for this user:
|
||||
|
||||
1. Log in as the bot user.
|
||||
2. Go to **My Account → Access Tokens**.
|
||||
3. Click **Generate** in the API row and copy the token.
|
||||
|
||||
### 2. Configure the plugin in OpenProject
|
||||
|
||||
Go to **Administration → Integrations → Gitea** and set:
|
||||
|
||||
- **Gitea actor** — the bot user created above. When set, only webhook requests authenticated with this user's API token are accepted.
|
||||
- **Webhook secret** — a shared secret used to verify the HMAC-SHA256 signature on incoming requests. Leaving this blank disables signature verification (not recommended).
|
||||
|
||||
### 3. Create a webhook in Gitea
|
||||
|
||||
In each Gitea repository (or at the organisation level), go to **Settings → Webhooks → Add Webhook → Gitea**.
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Target URL | `https://your-openproject.example.com/webhooks/gitea?key=<api_token>` |
|
||||
| HTTP Method | POST |
|
||||
| Content Type | `application/json` |
|
||||
| Secret | The same value entered as the **Webhook secret** in OpenProject |
|
||||
| Trigger | **Custom events** → check **Pull Request** and **Issue Comment** |
|
||||
|
||||
Replace `<api_token>` with the API token generated for the bot user.
|
||||
|
||||
> **Same-host installs:** If Gitea and OpenProject run on the same machine you may need to allow local network requests in Gitea's configuration (`[webhook] ALLOWED_HOST_LIST`).
|
||||
|
||||
### 4. Enable the Gitea module per project
|
||||
|
||||
In each OpenProject project go to **Project Settings → Modules** and enable the **Gitea** module. This makes the Gitea tab visible on work packages.
|
||||
|
||||
## How it works
|
||||
|
||||
```
|
||||
Gitea ──webhook──▶ /webhooks/gitea?key=<token>
|
||||
│
|
||||
HookHandler
|
||||
• verifies HMAC-SHA256 signature
|
||||
• checks user matches configured bot
|
||||
• dispatches OpenProject::Notifications event
|
||||
│
|
||||
┌────────────┴────────────┐
|
||||
▼ ▼
|
||||
NotificationHandler NotificationHandler
|
||||
::PullRequest ::IssueComment
|
||||
│
|
||||
UpsertPullRequest / UpsertGiteaUser
|
||||
│
|
||||
work_package.gitea_pull_requests (HABTM)
|
||||
│
|
||||
WorkPackages::UpdateService (posts journal comment)
|
||||
```
|
||||
|
||||
The work package split-view tab fetches linked pull requests via:
|
||||
|
||||
```
|
||||
GET /api/v3/work_packages/:id/gitea_pull_requests
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
Run the OpenProject test suite against this module:
|
||||
|
||||
```bash
|
||||
bundle exec rspec modules/gitea_integration/spec
|
||||
```
|
||||
|
||||
Lint Ruby:
|
||||
|
||||
```bash
|
||||
bundle exec rubocop modules/gitea_integration
|
||||
```
|
||||
|
||||
Lint TypeScript:
|
||||
|
||||
```bash
|
||||
cd frontend && npx eslint src/
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
GNU General Public License v3 — see [LICENSE](../../LICENSE).
|
||||
Reference in new issue
Block a user