Unblu logo

Setup

In order to interact with a given Gitlab instance through its REST API, u-needs-work needs to be authorized and authenticated. To do so, together with Gitlab’s instance URL, an API token must be provided.

GitLab: Generate an API Token

You will need a personal access token or a group access in order for the tool to interact with your repositories on GitLab.

All the actions are done using the REST API of GitLab.

You will need the api scope.

If you use a Group token, you will need the Developer role, since the tool is posting comments on Merge Request.

Application Setup

Some configurations are available for u-needs-work:

Example application.properties file
gitlab.host=https://gitlab.com
gitlab.api.token=glpat-rXzx1n17cqUnmo437XSf

You can use any of the Configuration Sources supported by Quarkus to set the values. For example you can use following system property to set the gitlab.api.token value:

Setting gitlab.api.token using a system property:
export GITLAB_API_TOKEN=glpat-rXzx1n17cqUnmo437XSf

GitLab host

Specify the location of the GitLab server:

GitLab api token

Specify the api token value used when u-needs-work is performing REST calls.

  • key: gitlab.api.token

  • No default value.

  • Mandatory for the application to start

GitLab: Webhook Setup

In the corresponding repository or group configure a Webhook pointing to the location where u-needs-work is available:

  • URL: <server url>/u-needs-work/event

  • Trigger: Comments events

Warning
 From an operational point of view, it might be safer to deploy u-needs-work to a server where only your GitLab instance has access.

Read more about the different available endpoints.

Dev setup

The application can be started locally, check local build section.

Working with a remote GitLab instance

If you are working locally with a remote gitlab instance (like https://gitlab.com/), adding some proxy might be useful:

With a tool like ngrok you will get a public url (something like https://2a01-8943-19d-e0a-8b20-645f-f7a2-c2d-9be1.ngrok.io) that points to your localhost computer.

start ngrok (assuming u-needs-work is running locally on port 8080)
ngrok http 8080

With a tool like mitmproxy you can proxy the remote instance to capture the REST requests made by u-needs-work to the remote instance:

start mitmproxy
mitmproxy -p 8888 --mode reverse:https://gitlab.com

And then make u-needs-work use localhost:8888 instead of gitlab.com directly:

use mitmproxy
export GITLAB_HOST=http://localhost:8888