# What is GitLab?
GitLab (opens new window) is a web-based management tool for Git repositories developed by GitLab Inc. It provides additional features such as issue-tracking, access-management, continuous integration, an integrated IDE, and many more. This section introduces some features of GitLab that are useful when using it in combination with ONE DATA Apps.
# Projects and access-management
In GitLab it is possible to create projects for hosting a codebase and working collaboratively on it. For every project one of the following visibility levels can be defined:
- Public: Everyone can view the code of the project even if they are not signed in.
- Internal: The code of internal projects can be accessed by any logged-in user.
- Private: Private projects can only be viewed by users that are members of the project.
Members of a project can be assigned certain access roles in the Members-page of the project settings. Every member can be assigned to one of the following permission levels (every level implies all permissions of the previous one):
- Guest: Guests can view the code and create issues. They are neither allowed to make changes to the codebase nor to create merge requests.
- Reporter: Reporters also can't modify the code, but can create merge requests and modify issues.
- Developer: Developers are allowed to create new branches and push to non-protected branches.
- Maintainer: Maintainers are allowed to push to protected branches and modify project settings. They can also manage the members of the project.
- Owner: Owners are allowed to change the basic properties of a project, like the visibility level and the project name. They are also allowed to delete the project.
For more detailed information about the permissions of the individual levels, please refer to the permission matrix (opens new window) in the GitLab documentation.
# Roles mapping from ONE DATA Apps
The ONE DATA Apps access roles translate to the GitLab permission levels as follows:
|ONE Apps role||GitLab permission level|
# Viewing branches and history
Once a project in GitLab is created, the repository can be explored in the web interface. This can be done via the repository menu in the left sidebar.
In the Files page the files in the repository can be seen. An example of this view is shown in the following figure:
The top bar contains a dropdown (1) to select the branch to be viewed. With this, any branch or tag in the repository can be chosen and the repository content (5) will change to the state in the selected revision. Furthermore, the top bar contains quick actions to view the history of the selected branch (2) and to directly edit the files in the integrated editor(3). The "Clone" dropdown (4) can be used to view the repository URLs that are needed for checking out the repository locally. This will be described in more detail below. Under the top bar the most recent commit (5) that was made to the selected branch is shown.
The Commits page is accessible via the left sidebar and can be used to view the commit history of the branches in the repository.
Like in the Files-page the currently shown branch can be selected using the dropdown (1) in the top bar. With the button at the right (2) a merge request from the selected branch into another branch can directly be created. The commit list below shows the commit history of the selected branch. The most recent commit (3) is shown at the top with its commit message and its author. On the right side, the commit hashes (4) are shown with quick actions to copy the hash and view the repository files at the respective version.
Via the Repository-menu it is possible to access the Branches page that allows to browse all branches of the repository.
In the top bar, a button (1) to delete merged branches can be found. This can be used to clean up the repository by deleting all branches which were already merged back into develop. With the button to the right (2) a branch directly be createdin the GitLab UI specifying a branch or commit that should be the starting point of the new branch. The branches list itself (3) is separated into active and stale branches. A branch is active if a commit was recently pushed to it. If no change was made to a branch for some time, it will be listed as a stale branch. With the quick actions available for each branch a merge request (4) from the branch can be created, changes of the branch to another branch or tag can be compared (5) and the branch can be deleted (6). Some branches are also labeled with badges. The branch marked with "default" (7) is the main development branch and will be the default target when creating merge requests. Branches labeled "protected" (8) can only be pushed to by users with the Maintainer permission level or higher privileged roles. These are typically the main development branch (develop) and the live branch (master). The badge "merged" (9) indicates that the branch was merged into the default branch and thus can be deleted without losing progress.
# Merge Requests
With a merge request (MR) a project maintainer is requested to merge the changes made on a branch into another branch (typically develop). It is a tool to visualize the changes and to discuss them. The assignee of the merge request can review the changes, give feedback, and merge them to the target branch once they approve the changes.
A merge request can be created via the means discussed above or by going to the merge requests page in the left sidebar and clicking Create merge request.
On the merge request creation page, the branch that should be merged
(1) and the target branch (2) that should receive the changes can be selected.
Below a title for the merge request and a description of the changes made can be set. Furthermore, an assignee (4) who should review the merge request need to be chosen. If the merge request targets a protected branch, the assignee must be a maintainer or owner of the project. GitLab will give a waring if an assignee is chosen who is not allowed to perform the merge. At the bottom, labels (5) for the merge request can be chosen. These can vary from project to project and can for example indicate required actions such as testing or an UI review.
Once the merge request is created, one is brought to the merge request page and the assignee can start reviewing the changes.
The merge request page has three tabs of which the most important are the
Overview tab (1) shown in the figure above and the Changes tab (2) that will
be described later.
The overview tab shows the properties of the merge requests like the description, the source branch, and the target branch. Furthermore, it contains the option to merge the changes (3). While it may be technically possible to merge the MR oneself, this should only be done by the assignee. The overview page also lists all activity in the merge request like discussions (4) and pushes since the merge request was created. A discussion can be started at the bottom or by commenting on the code in the Changes tab. Discussions can be used by the assignee to give feedback or by the author to raise questions. Once a discussion is finished it can be marked as resolved (5). It is not possible to merge a MR if there are unresolved discussions.
The Changes tab shows all the changes that will be introduced on the target branch by the merge. The assignee can go through them and add comments.
At the top, the total amount of changes is displayed (1). It shows the number of files changed, the number of lines added and the number of lines removed. On the left side, a file tree (2) with the modified files that can be used to quickly navigate to changes that were made can be seen. The main view visualizes the changes made to the files (3). Red lines will be removed and green lines will be added by the merge. GitLab also highlights the parts of the lines that changed for a better overview. By hovering the mouse over the line number, a small speech bubble appears that can be used to start a new discussion on that line.
# Resolving merge conflicts
As described above, conflicting changes may be introduced on the target branch while working on a feature branch. In this case, it is necessary to manually resolve the conflicts to be able to merge the branch. In GitLab merge requests conflicts are indicated as shown below.
By clicking on Resolve conflicts the conflicts can be resolved directly in the GitLab UI.
On the conflict resolution page, all conflicts of the merge are highlighted. The changes from the source branch are shown in green (1). The conflicting changes at the target branch are shown in blue (2). Either of them can be chosen by clicking Use ours or Use theirs at the right (3). If none of the changes makes sense in the merged context, it is possible to also choose Edit Inline (4) to bring up an editor to make changes to the file. Once changes are done clicking Commit to source branch, which will create a merge commit on the branch. Afterwards the merge request can be merged again. Please note that the branch should be retested to make sure that everything is fine after resolving the conflicts.
# Cloning to a local repository
Although GitLab provides powerful features to edit and manage a repository in the web interface, sometimes it is useful to check out the repository on the local machine. This section describes how to check out the repository locally. For cloning the repository the repository URL is needed. This can be found in the Clone dropdown of the Files page. There a URL for the SSH-protocol and one to perform a checkout via HTTPS can be found. Those URLs can be used to clone the repository to a local machine with the following command:
git clone email@example.com:apps/my-repo.git
This command will create a folder with the name of the repository in the current working directory. Alternatively, tools like SourceTree (opens new window) can be used to clone the repository.
The most convenient way to check out a repository is via SSH. This requires that SSH is accessible at the GitLab-instance. With SSH the SHH public key only needs to be added once to the GitLab account, meaning that any respository can be checked out without further authentication required. To add a key, go to the account settings by clicking the profile picture in the upper-right corner and choose Settings and then go to SSH Keys.There the public key can be pasted and assigned a name. If keys are managed with Putty under Windows, they can be converted to the required format with following command:
ssh-keygen -i -f my-key.pub
Once the key is saved, it can be cloned to any repository that one has to via the SSH-URL as described above.
If the repository is cloned via HTTPS it is necessary to enter credentials every time pushing or pulling changes. In case an OAuth login is used (for example if logging in to GitLab with ONE DATA credentials) an access token needs to be created in order to be able to authenticate via HTTPS. To create a token, click the profile picture in the upper-right corner and choose Settings, and then go to Access Tokens.
Enter a name for the token and check read_repository and write_repository. Clicking Create personal access token will generate a token that can be used as a password when authenticating via HTTP(S) with Git. Please make sure to save the token as it is not possible to access it again once leaving the page.