GitLab

Modified on Sun, 10 Apr 2022 at 11:11 PM

This article is outdated, you can access the most current version here: https://doc.onedata.de/apps/apps-docs/odml-documentation/AppBuilder/git-management/GitLab.html

Article Content

Article Content
What is GitLab?
Projects and access-management
Viewing branches and history
Merge Requests
- Resolving merge conflicts
Cloning to a local repository

What is GitLab?

GitLab 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, you can create projects for hosting your 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 he/she is 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 not allowed to make changes to the codebase or 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.

If you need more detailed information about the permissions of the individual levels, please refer to the permission matrix
in the GitLab documentation.

Viewing branches and history

Once you created a project in GitLab, you can explore the repository in the web interface. This can be done via the repository menu in the left sidebar.

In the Files page you can view the files in the repository. An example of this view is shown in the following figure:

The top bar contains a dropdown (1) to select the branch you're looking at. With this, you can choose any branch or tag in the repository 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 (4) 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 your repository.

Like in the Files-page you can select the currently shown branch using the dropdown (1) in the top bar. With the button at the right (2) you can also directly create a merge request from the selected branch into another branch. 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 you can also access the Branches page that allows you to browse all branches of the repository.

Inside the top bar, you can find a button (1) to delete merged branches. 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) you can create a branch directly in 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 you can create a merge request (4) from the branch, compare (5) the changes of the branch to another branch or tag, and delete (6) the branch. 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) you request a project maintainer to merge the changes made on your 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 he/she approves 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, you can select the branch you want to merge (1) and the target branch (2) that should receive the changes.
Below you can set a title for the merge request and a description of the changes made. Furthermore, you need to choose an assignee (4) who should review the merge request. If the merge request targets a protected branch, the assignee must be a maintainer or owner of the project. GitLab will warn you if you chose an assignee who is not allowed to perform the merge. At the bottom, you can also choose some labels (5) for the merge request. These can vary from project to project and can for example indicate required actions such as testing or an UI review.

Once you choose to create the merge request, you are 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 yourself, 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. You can start a discussion 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, you can see a file tree (2) with the modified files that can be used to quickly navigate to changes. The main view visualizes the changes made to the files (3). Red lines are removed by the branch 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 you're working on yours. 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 you can resolve the conflicts 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). You can choose either of them by clicking Use ours or Use theirs at the right (3). If none of the changes makes sense in the merged context, you can also choose Edit Inline (4) to bring up an editor where you can make changes to the file. Once you are happy with the changes, you can click Commit to source branch, which will create a merge commit on your 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 your repository in the web interface, sometimes you may want to check out the repository on your local machine. This section describes how you can check out the repository locally. For cloning the repository you need the repository URL. This can be found in the Clone dropdown of the Files page. There you can find an URL for the SSH-protocol and one to checkout via HTTPS. You can use one of these URLs and clone the repository to your local machine with the following command:

git clone git@instance.onedata.de:apps/my-repo.git

This command will create a folder with the name of your repository in the current working directory. Alternatively, you can use tools like SourceTree to clone the repository.
The most convenient way to checkout a repository is via SSH. This requires that SSH is accessible at your GitLab-instance. With SSH you only need to add your SSH public key once to your GitLab account and then you can checkout any repository without further authentication required. To add your key, go to your account settings by clicking your profile picture in the upper-right corner and choose Settings and then go to SSH Keys. There you can paste your public key and assign a name to it. If you're managing your keys with Putty under Windows, you can convert your key to the required format with the following command:

ssh-keygen -i -f my-key.pub

Once you saved your key, you should be able to clone any repository that you have access to via the SSH-URL as described above.

If you choose to clone the repository via HTTPS it is necessary to enter your credentials every time you push/pull changes. In case you use an OAuth login (for example if you login to GitLab with your ONE DATA credentials) you need to create an access token in order to be able to authenticate via HTTPS. To create a token, click your 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 you can use 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 you leave the page.