Why integrate Redmine and Gitlab ?

Redmine is a project management project, Gitlab a source management so what can why would we want to integrate them ?

  • Users: if you're using both systems, you don't necessarly want to waste time creating users in both systems.
    The better options is being able to create the user in one platform and have it automatically be created in the other(s)

  • Issues: Gitlab will usually be used by Dev teams whereas Redmine will be for Project managers or support teams. This means that issues/tickets created in one system will only be visible by a limited population.
    An easy way to keep everyone informed is to have issue/ticket management centralised on a single platform, moreso if user integration has been set up.

SSO: push Gitlab users to Redmine - redmine_omniauth_gitlab

Using Redmine plugin omniauth_gitlab we can create users in Gitlab and simplify the user creation in Redmine.

Gitlab configuration

Connect to your Gitlab UI with administrator level access and go to "Admin area" > Applications


Field Description
Application Name of your choice.
Set to Redmine for our current example.
Application ID Will be set by Gitlab when saving the form.
Secret Will be set by Gitlab when saving the form.
Can only be seen once so keep it saved safely otherwise you will need to renew it meaning updating configuration of all platforms using that secret.
Callback URL Your Redmine "oauth2callback" endpoint.
Example for my Redmine at URLhttps://redmine.nicksopenworld.com :
Trusted Yes
Can be set to untrusted and the authentication still works but trusting the applications means it's automatically authorized on GitLab OAuth flow.
Confidential Yes
Required: this forces the use of the secret, securing the authentication configuration.
Scope api
Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry.

Redmine configuration

Redmine server : installing the plugin

Connect through SSH to your Redmine server and clone the module in your Redmine plugins directory ( "/opt/redmine/plugin" in the example below):
cd /opt/redmine/plugin
sudo git clone https://github.com/applewu/redmine_omniauth_gitlab.git

And restart your Redmine instance:

  • Docker based with container named Redmine
    Setting docker parameter REDMINE_PLUGINS_MIGRATE to TRUE, once plugin has been cloned you only need to restart the container:
    sudo docker restart Redmine

  • Standard Redmine installation
    Install the plugin and restart Redmine:
    cd /opt/redmine
    bundle install
    bundle exec rake redmine:plugins:migrate RAILS_ENV=production
    rake redmine:plugins RAILS_ENV=production
    sudo touch /opt/redmine/tmp/restart.txt

Redmine UI : configure the plugin

Connect to your Redmine UI with administrator level access and go to "Administration" > Plugins


And go thoe the Redmine Omniauth gitlab plugin configuration pannel:

Field Description
Your Gitlab Website URL URL for your Gitlab instance.
Value for my example:
Client ID Application ID for the Redmine Gitlab application set up previously.
Client Secret Secret used by the Redmine Gitlab application set up previously.
Callback URL Your Redmine "oauth2callback" endpoint.
Example for my Redmine at URLhttps://redmine.nicksopenworld.com :
Available domains Set the domains you want to allow for this connection.
If left empty, anyone can login using the Gitlab authentication.
Adding a domain restricts to only authorized domains, setting a pre-filter.
Even if all domains are allowed, account creation & activation is ultimately defined by Redmine's Self-registration policy configuration.
Oauth authentification Yes
If ticked of, the "Login via gitlab" button will no appear on Redmine's /login. page

Once all is configured, you will see the "Login via gitlab" button on Redmine's login page:

This button will send you to your Gitlab's login page and the redirect you to Redmine once authentified.

Redmine’s self-registry configuration

In Redmine's Administration > Settings can be configured the self registration policy.

Setting Description
Disabled The Gitlab Omniauth plugin or any other SSO self-registration plgins will not work.
Account activation by email An email is sent to user allowing for autonomous user creation but proper ressource access might not be given depending on the default Redmine groups assigned to newly created users.
Manual account activation Account is created pending Redmine Administrator validation.
Usefull to add a filtering layer and have an opportunity to properly configure user access/groups.
Automatic account activation Redmine account is accessible on first login but proper ressource access might not be given depending on the default Redmine groups assigned to newly created users.

Avoid spam by using Available domains filter

Because in the Available domains we've only allowed nickopenworld.com, any user registered on Gitlab with an email from another domain will not be able to use that plugin.

Usage and conclusions

Once all is configured, you should be able to create users in Gitlab and have them access Redmine with limited configuration but it has a few limitations.

Pros Cons
- Only 1 account to manage for users accessing both platforms.
- Even if multiple companies/entities can access your Gitlab platform, you can filter access to Redmine
- Combining the proper Redmine self-registration settings and Redmine groups configuration,you can still fine tune Redmine ressources access.
Even if the account is automatically created, if will only see public ressources and projects available by default.
- If the Gitlab platform is down, users won't be able to access Redmine
- If not everyone can access both platforms, you will still be left with 2 platforms in which you will have to manage user accounts
- Gitlabs groups are not maanged by the plugin so you will still need to take time to configure Redmine account configuration.

My conclusion is that although the plugin is limited, it still implifies everyday administration:

  • End users only have 1 account to remember
  • Even if you need to finish user confguration manually in Redmine, the users are automatically created so you only need to configure the groups to wich users must be associated
  • Depending on the criticity and secrecy requirements, Redmine projects can be made public while still requiring users to log in. If so, the ressources will be available without the intervention of a Redmine administrator

Issue management: use Redmine as issue management platform for Gitlab project(s)

No plugin manamgenet is required here and all is described in Gitlab documentation: External issue trackers > Redmine

This configuration basically creates a link in Gitlab projects to a Redmine project.

At instance level

This will set a link to a Redmine project for all Gitlab projects meaning issues for all Gitlab projects will be managed in the same Redmine project.

Connect to your Gitlab UI with administrator level access and go to "Admin area" > Settings > Integrations.
Find Redmine and configure:

In the example below we have created a Redmine projet "general project":

When saving, you will have a notification warning:

Once set, any existing project in Gitlab and all new projects will have a link to that Redmine project by default.

At project level

If you want a more granular management or only some projects to have a dedicated Redmine project, the configuration can also be done at project level.

Connect to your Gitlab UI with administrator level access and go to your pojectSettings > Integrations.

If Redmine integration has been configured at Instance level, you will be asked if you want to use Default or Custom settings:

Configuration is the same as for Instance level integration but using different URLs for each Gitlab project:

Once configured

Wichever level you have decided to configure at, the result is that when accessing Gitlab projects you will now have a link to a Redmine project:

This will require:

  • that the Redmine project be public and accessible without having to log into Redmine
  • that users can access both Gitlab and Redmine projects
    In which case, the Gitlab user integration to Redmine seen above is strongly recommended.

Warning: This does not block usage of the built-in Gitlab issue management tool.
And there is no synchronisation between Gitlab issues and Redmine isssues: any issues created in Gitlab will not be pushed or available in Redmine.
A workaround is to export issues from Gitlab in CSV format and import these issues into Redmine.

Show in Redmine the merge requests associated with an issue - Redmine Merge Request Links

Disclaimer: I have never used this in a Production environment but thought it would be good to mention it exists.

Although the Redmine plugin repository page doesn't indicate support for Redmine 5.X, it works and can be quite useful.

The documentation is quite complete and up to date on the Redmine merge request Github page.

Final thoughts

Each of the elements presented here are independent.
You can decide the level of integration between Gitlab and Redmine depending on your usage of both platforms.

But always go for the solution(s) that has the easiest maintenance while adding value to your workflow.

0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x