OpenProject plugin: Scripts (Experimental)

⚠️ Experimental code — do not install on any critical or production infrastructure. This plugin lets an admin execute arbitrary Ruby with full application privileges. It has not been hardened, audited, or reviewed for production use, and it is not intended to be.

Purpose

This plugin is an experiment, not a product. Its goal is to get a feel for what radical extensibility in OpenProject could be like — inspired by Jira's ScriptRunner — by giving an instance admin the ability to write custom Ruby and have it run automatically on specific events, sucha as work packages or projects created/updated, comments added, time entries or attachments created.

The point of this experiment is to trigger new ideas about what extensibility in OpenProject might look like, not to arrive at a finished feature. Nothing here should be read as a proposal to ship "exactly this." If it sparks a direction worth pursuing, that direction will very likely look different from this experiment once real design, security, and product considerations are applied.

What it does

An admin writes Ruby code, saves it as a script, and subscribes it to one or more of the same events OpenProject's built-in Webhooks feature already fires on. When a matching event occurs, the script runs inside a Proc, receiving the event name, the acting user, and the live domain object(s) involved (the work package, project, journal, etc.).

On work package creation or updates the script can either run asynchronously in the background, not intercepting the user's request. Or it can intercept the user's request to exexute right after a work package was created or updated.

This plugin requires an Enterprise token as this — if ever implemented for produciton — is clearly an enterprise feature, if ever developed for production.

This is deliberately modeled on OpenProject's built-in Webhooks feature — same event catalog, same admin menu placement (a sibling of Webhooks under Administration → API and webhooks), same async delivery via a background job.

See docs/development/create-openproject-plugin in OpenProject core for the general plugin mechanism this follows.

Requirements

• OpenProject >= 17.9.0
• An Enterprise token granting the running_scripts feature, to actually create/edit/enable scripts through the admin UI (the admin menu item, and read-only access to existing scripts, remain visible without one — an upsell banner is shown instead).

Installation

Add this plugin to your OpenProject installation's Gemfile.plugins, inside the opf_plugins group:

group :opf_plugins do
  gem "openproject-scripts", path: "../plugins/openproject-scripts"
end

Then run bundle install and bundle exec rails db:migrate from your OpenProject core checkout.

For Docker-based installations, see the Docker plugin installation guide. For packaged (deb/rpm) installations, see the packaged plugin installation guide.

Reaching the Scripts admin page

Once the plugin is installed and a correct Enterprise token is provided, sign in as an instance administrator and open the admin area:

1. Click your avatar in the top-right corner and choose Administration (or go directly to /admin).
2. In the left-hand admin menu, expand API and webhooks.
3. Select Scripts.

From there you can create, edit, enable, and disable scripts, and pick which events they subscribe to. The menu item is only shown to admins; without a valid Enterprise token the page is read-only and displays an upsell banner instead of the create/edit actions.

Uninstallation

Remove the gem "openproject-scripts", ... line from Gemfile.plugins and run bundle install again. Existing scripts_* database tables are left in place; drop them manually via a migration if you want them removed too.

Bug reports and contributions

Please raise issues, questions, and feedback on the OpenProject Community.

License

GPLv3, matching OpenProject core. See COPYRIGHT and LICENSE in OpenProject core for details.