openproject_gitea_plugin/README.md

OpenProject Gitea Integration

An OpenProject module that integrates Gitea 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:

• Its semantic ID: KS-10, PROJ-42 — matched automatically, no prefix needed
• A prefixed numeric ID: OP#42 — prefix required to avoid collision with Gitea issue numbers
• A full OpenProject URL: https://openproject.example.com/work_packages/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):

group :opf_plugins do
  gem 'openproject-gitea_integration', '~> 1.0'
end

Tell OpenProject to use it and trigger a recompile of frontend assets:

openproject config:set CUSTOM_PLUGIN_GEMFILE=/etc/openproject/Gemfile.custom
openproject config:set RECOMPILE_ANGULAR_ASSETS=true
sudo openproject configure

Docker / docker-compose installation

The official OpenProject Docker image bakes all gems and frontend assets in at build time, so installing a third-party plugin requires building a custom image. The docker-compose.yml provided by OpenProject is overwritten on every update, so all local changes go into docker-compose.override.yml and a separate Dockerfile that you own.

1. Clone the plugin

git clone https://github.com/quafzi/openproject-gitea-plugin.git \
  openproject-gitea-plugin

Place it anywhere convenient — this guide assumes it sits next to your docker-compose.yml.

2. Create Dockerfile.gitea

FROM openproject/openproject:17

USER root

# Copy the plugin source into the image
COPY --chown=app:app openproject-gitea-plugin \
     /app/modules/gitea_integration

# Register the gem and recompile assets
RUN echo 'group :opf_plugins do\n  gem "openproject-gitea_integration", path: "modules/gitea_integration"\nend' \
    > /app/Gemfile.plugins && \
    cd /app && \
    bundle install --without development test && \
    RAILS_ENV=production bundle exec rake \
      openproject:plugins:register_frontend \
      assets:precompile

USER app

3. Create docker-compose.override.yml

This file is never touched by OpenProject updates. Point both web and worker at your custom image — they must use the same image so the plugin is loaded in both processes.

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile.gitea
    image: openproject-with-gitea:latest

  worker:
    build:
      context: .
      dockerfile: Dockerfile.gitea
    image: openproject-with-gitea:latest

4. Build and start

docker compose build
docker compose up -d
docker compose exec web bundle exec rails db:migrate

Updating the plugin

cd openproject-gitea_integration && git pull && cd ..
docker compose build --no-cache
docker compose up -d
docker compose exec web bundle exec rails db:migrate

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):

   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:

   bundle install
   

4. Run the database migration:

   bundle exec rails db:migrate
   

5. Rebuild the frontend:

   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:

bundle exec rspec modules/gitea_integration/spec

Lint Ruby:

bundle exec rubocop modules/gitea_integration

Lint TypeScript:

cd frontend && npx eslint src/

License

GNU General Public License v3 — see LICENSE.