search

btey / openproject-gitlab-integration

OpenProject module for integration with Gitlab
GNU General Public License v3.0
83 stars 18 forks source link

readme

NOTE: This plugin is now part of OpenProject Core 🥳

As of opf/openproject#14881 this plugin was merged into OpenProject core v13.4. Hence, further changes or improvements will be made directly within OpenProject.

Already using the user-generated GitLab plugin? With OpenProject 13.4, the existing plugin will be replaced by the new integration. We recommend removing the plugin module folder and bundler references before upgrading to openproject. Your historical dataset will remain unaffected within OpenProject as there were no changes to the data model.

Before upgrading, please do the following:

  1. Remove traces of gitlab integration in your Gemfile.lock and Gemfile.modules See Configuration section
  2. Remove the module code traces of the gitlab integration. rm -rf /path/to/openproject/modules/gitlab_integration

Many thanks to everyone who worked on this plugin – inside and outside of OpenProject's core development team! Such projects are a great example of the power of open source collaboration.💙

Introducing OpenProject GitLab Integration v2.1.6 GA

Based on the OpenProject Github Integration, this plugin offers the same functionalities plus other new features. This is the first version that includes the visualization of the status of the Pipelines (by now, it is considered in Beta status). You can test it by activating the Pipelines event in the GitLab webhook. Just keep in mind that not all pipelines will be reflected in OpenProject, only Merge Request type pipelines (for more information see the GitLab issue https://gitlab.com/gitlab-org/gitlab/-/issues/345028). Any feedback about the pipelines feature would be very appreciated, whether it works or if issues arise (you can use this ticket https://github.com/btey/openproject-gitlab-integration/issues/43).

In this version it has also been implemented that all linked or referenced Issues appear in the GitLab tab (https://github.com/btey/openproject-gitlab-integration/issues/34). The opportunity has also been taken to redesign how the information is presented so that it is visually easy to read and at the same time can continue to provide all the information, including labels and pipeline status.

If there are labels related to the Issue or MR, a button with the label icon will appear. By clicking the button you can show/hide the associated labels.



Overview

OpenProject module for integration with GitLab:

The reference system is based on the same system as for GitHub integration. You can use a link to the work package or just use “OP#87” or "PP#87" in the title/description of the Issue/MR in GitLab.

Note about the references. Whether or not to include the reference in certain places depends on the information that GitLab sends through its webhook. If you include the reference in the title/description of an issue, the comments on the issue do not need to include the reference. The same will happen when you generate a Merge Request based on an Issue that already includes the reference; comments from that MR need not include the reference.

Difference between OP and PP

If you use OP# as a reference in an Issue or MR title, all comments will be replicated in OpenProject. However, sometimes you may only want to keep information about the status of an Issue/MR in OpenProject, but you don't want your comments to be published. In this case, you can use PP# as a reference. This way the comments will not be published in OpenProject. But if at any time one of your comments in a private Issue/MR is of interest to you to be published in OpenProject you can use OP# directly in that comment. So only that comment will be published in OpenProject. The rest of the comments will remain private and will not be published.

Available events captured in OpenProject

OpenProject will add comments to work package for the following events:

OpenProject will update WP status in this events:

Note about the status. If you want to change the ID of the status you can do this in this section of the code. By default is disabled, you can enable it by setting to true this lines.

Example workflow

A typical workflow on GitLab side would be:

  1. Create Issue.

    Issue Opened: Issue 6 New contact form - OP#18 for Scrum project has been opened by Administrator.

  2. Comment on issue.

    If the reference is included in the title, the comments will not need a reference. By default, all comments will use the title as a reference.

    Commented in Issue: Administrator commented this WP in Issue 6 New contact form - OP#18 on Scrum project:

    New comment on the issue with attachment.

  3. Create Merge Request.

    MR Opened: Merge request 25 Draft: Resolve "New contact form - OP#18" for Scrum project has been opened by Administrator.

    Status changed from Specified to In progress

  4. Comment in Merge Request.

    Commented in MR: Administrator commented this WP in Merge request 25 Draft: Resolve "New contact form - OP#18" on Scrum project:

    New comment on MR.

  5. Reference in other Issues or Merge Request (comments).

    If the reference is NOT included in the title of the Issue/MR, the comments will need a reference. In OpenProject the comment will be saved as "referenced" in Issue/MR.

    Referenced in Issue: Administrator referenced this WP in Issue 2 New backend pipeline on Scrum project:

    OP#18 New comment about...

    Note: If you use the reference PP# in the title of the Issue/MR, you can use OP# in the comment to generate the same type of comment in OpenProject.

  6. New commit in Merge Request.

    Pushed in MR: Administrator pushed fca3d6fb to Scrum project at 2021-03-08T08:01:57+00:00:

    Update readme.md OP#18

  7. Comment in a new commit of the Merge Request.

    Referenced in Commit: Administrator referenced this WP in a Commit Note 0bf0e3e9 on Scrum project:

    This change is for OP#18.

  8. Merge Request merged (generates up to 3 events).

    Pushed in MR: Administrator pushed 1da09cb4 to Scrum project at 2021-03-05T14:57:37+00:00:

    Merge branch '5-new-contact-form-op-18' into 'master'

    Resolve "New contact form - OP#18"

    Closes #6

    See merge request root/scrum!9

    MR Merged: Merge request 24 Resolve "New contact form - OP#18" for Scrum project has been merged by Administrator.

    Status changed from In progress to Developed

    Issue Closed: Issue 6 New contact form - OP#18 for Scrum project has been closed by Administrator.

Configuration

You will have to configure both OpenProject and Gitlab for the integration to work.

In case of Docker installation, follow the official OpenProject documentation here. If for some reason the installation with Docker described in the official documentation does not work for you, you can try building your own docker image:

In case of DEB/RPM based instalation, follow the official OpenProject documentation here.

In case of manual installation, this plugin should be installed in the same place as the Github plugin that comes bundled with OpenProject.

But first you must modify Gemfile.lock and Gemfile.modules so that OpenProject detects the new module.

Add the following in Gemfile.lock:

PATH
  remote: modules/gitlab_integration
  specs:
    openproject-gitlab_integration (2.1.6)
      openproject-webhooks

And add this other line in DEPENDENCIES section:

DEPENDENCIES
...
  openproject-github_integration!
  openproject-gitlab_integration!
  openproject-job_status!
...

Add the following in Gemfile.modules:

group :opf_plugins do
...
  gem 'openproject-gitlab_integration',        path: 'modules/gitlab_integration'
...
end

Note: It's possible that you need to use these commands before and after the bundle install if you get an error in this step warning about a change in the Gemfile:

bundle config unset deployment
bundle install --deployment --without mysql2 sqlite development test therubyracer docker
bundle config set deployment

The GitLab Bot user in OpenProject

First you will need to create a user in OpenProject that will make the comments. The user will have to be added to each project with a role that allows them to comment on work packages and change status.

Once the user is created you need to generate an OpenProject API token for it to use later on the Gitlab side:

The webhook in GitLab

In GitLab you have to set up a webhook in each project or in a group (Premium Users) to be integrated with OpenProject.

You need to configure just two things in the webhook:

  1. The URL must point to your OpenProject server’s GitLab webhook endpoint (/webhooks/gitlab). Append it to the URL as a simple GET parameter named key. In the end the URL should look something like this:

    http://openproject-url.com/webhooks/gitlab?key=[previous_generated_access_token_key]

  2. Enable the required triggers:

    1. Push events (project hooks or systems hooks)
    2. Comments
    3. Issues events
    4. Merge request events
    5. Pipeline events

Now the integration is set up on both sides and you can use it.

Note: If you are installing and configuring OpenProject on the same server as GitLab you will need to enable in Gitlab the option Allow requests to the local network from web hooks and services so that it can send the data locally to the OpenProject webhook since they will be on the same machine.

How to report bugs or issues

Any error, bug or issue can be reported by creating a new issue.