# Bug DOCU-839 - [minor] Clarification needed in GitLab integration documentation (user vs role confusion)

Project: Documentation
Status: new
URL: https://community.openproject.org/work_packages/DOCU-839

## Open points

_No work packages_

## Details

| Attribute | Value |
| --- | --- |
| Date |  |
| Priority | Low |
| Module | Integrations / GitLab |
| Target versions | 17.7.0 |
| Observed in versions |  |
| Bug found in version (deprecated) |  |
| Requires doc change | Yes |
| Accessibility | No |
| Pull preview |  |
| List |  |
| Labels |  |

## People

| Attribute | Value |
| --- | --- |
| Assignee | Maya Berdygylyjova |
| Accountable |  |
| Product manager |  |
| Developers |  |
| Designer |  |
| Ordered by |  |
| Signed off by |  |
| Interest by |  |

## Planning

| Attribute | Value |
| --- | --- |
| Relevance |  |

## Costs

| Attribute | Value |
| --- | --- |
| Votes |  |
| Effort (shirt size) |  |
| Work |  |
| Labor costs |  |

## Description

Hi,  
I noticed a confusing part in the GitLab integration documentation, specifically in this section:  
[https://www.openproject.org/docs/system-admin-guide/integrations/gitlab-integration/#openproject](https://www.openproject.org/docs/system-admin-guide/integrations/gitlab-integration/#openproject)

The text currently says:

> “First you will need to create a user in OpenProject that has the permission to make comments. This role only requires two permissions, _View work packages_ and _Add notes_, which you will find in the Work packages and Gantt charts section under Roles and Permissions.”

The issue is that the documentation mixes the concepts of **user** and **role**:

*   The text says to “create a user”, but the screenshot actually shows the creation of a **role**.
    
*   Later in the page, the example shows adding a **user** to a project, which reinforces the confusion.
    
*   The screenshot also does not show the **Global role** option, which should _not_ be selected. This could mislead administrators who are not familiar with the distinction.
    

Because of this, it’s unclear whether the reader should first create a role, then assign it to a dedicated “GitLab User”, or whether the instructions refer to something else.

### **Suggestion**

A simple improvement would be:

*   Add a screenshot showing the creation of the **“GitLab User”** account.
    
*   Clarify the sequence:
    
    1.  Create a **role** with the two required permissions.
        
    2.  Create a **user** (e.g., “GitLab User”).
        
    3.  Assign this user to the project with the previously created role.
        
*   Optionally mention that **Global role** should remain unchecked.&nbsp;
    

This would remove the ambiguity and make the setup steps much clearer.

Thanks for your work on the documentation!
