---
layout: page
title: Help
permalink: /help/
ref: help
lang: en
---

Here you find some first aid on the use of JLU GitLab, but it cannot replace the [official user help](https://gitlab.test.uni-giessen.de/help/user/index.md){:target="_blank"}.
For specific information about JLU GitLab, see [information]({{ '/information/#what_is_jlugitlab' | relative_url }}).

## Content {#toc}

<!-- NOTE this is (currently) just a manually maintained list. -->
- [Important concepts](#essential_terms)
    - [Git terminology](#terms_git)
    - [GitLab terminology](#terms_gitlab)
- [How to use GitLab?](#how_to_gitlab)
- [First steps](#first_steps)
- [Visibility of projects](#project_visibility)
- [User roles in projects](#project_roles)
    - [Permissions as *Guest*](#project_guest)
    - [Permissions as *Reporter*](#project_reporter)
    - [Permissions as *Developer*](#project_developer)
    - [Permissions as *Maintainer*](#project_maintainer)
    - [Permissions as *Owner*](#project_owner)
- [User groups](#group)
    - [Visibility of groups](#group_visibility)
    - [User roles in groups](#group_roles)
- [Settings concerning private information](#settings_privacy)
- [Last steps](#last_steps)
- [How to delete my account?](#deletion_account)
- [Further help](#more_help)


## Important concepts {#essential_terms}

Git and GitLab are versatile tools with many technical concepts and terms.
Because their development and terminology is created in English, these terms have been only partially translated into other languages.
To keep the following help entries (e.g. regarding read and write permissions) short and comprehensible, the essential terms are explained here in plain English.
This is only a well-intended overview; [further help](#more_help) provides a collection of links to familiarize yourself with these concepts.

### Git terminology {#terms_git}

- [*Git*](https://en.wikipedia.org/wiki/Git){:target="_blank"} is the name of a software for version control of files.
- A *repository* is a collection of files where edits are versioned as a history of snapshots.
  With Git, you can manage multiple separate repositories.
- A *commit* is one snapshot of the data in the repository.
  Upon creation of a commit, the configured email address, name, date, time and an arbitrary comment become indivisibly connected with the file contents of the new snapshot.
  This is a fundamental security feature of Git to prevent future changes of this snapshot.
  [Read here](#settings_privacy) how to change these potentially private settings.
- A *branch* is a subset of snapshots with an arbitrary name, and helps to keep a repository neat and tidy.
- The Git commands *pull* and *push* can synchronize branches of Git repositories across devices (such as your own computer and JLU GitLab).
  Once two repositories are synchronized, they have both a copy of all data, i.e. the full history of snapshots.

### GitLab terminology {#terms_gitlab}

- A *project* on (JLU) GitLab nearly always contains a Git-Repository, and offers many additional functions for its management.
  In addition, GitLab offers multiple systems to automatically execute source code within the project, e.g. to run tests or to generate a website (like this one).
- Every project is assigned to a *namespace* of a user or a group.
  All users have their own namespace for their personal projects.
  Likewise, all user groups have their own namespace for group projects.
  Your read and write permissions in a project depend indirectly on the namespace:
  For projects in the namespace of other users, your permissions depend on the [project's visibility](#project_visibility) and if you are a project member, [your role in the project](#project_roles).
  For group projects, the permissions depend further on the [group's visibility](#group_visibility) and for group members on [their role in the group](#group_roles).
<!-- NOTE, not needed?: - With a *merge request* you can ask to merge one or multiple commits from one Git repository into another one. -->


## How to use GitLab? {#how_to_gitlab}

TODO: Browser sufficient for many smaller things, for serious work you should install Git locally.

TODO: Note existence of Git GUIs (maybe including endorsement)?

TODO: Refer to Git functions within Matlab and other IDEs?


## First steps {#first_steps}

TODO: Rough overview, links to good resources for learning more ([see further help below](#more_help)).

TODO: Where to find language setting.

TODO: Link to guided Tour within GitLab (or is this just an EE feature?).

<!-- TODO, see issue #35 in admin repo; Insert: "Now might be a good time to consider changing your username, if you want to"? -->


## Visibility of projects {#project_visibility}

Every project has a visibility setting as either *private*, *internal*, or *public*.
The visibility can only be changed by the *Owner* of the project (see [user roles below](#project_roles)).

- Projects with *private* visibility are only visible to the [members of the project](#project_roles).
- Projects with *internal* visibility are visible to anyone with a user account who is logged in.
- Projects with *public* visibility are also visible for people without a user account.

[Please read here]({{ '/information/#potential_users' | relative_url }}) what the visibility levels *internal* and *public* mean in the case of JLU GitLab.
For more details, please refer to the [official documentation](https://gitlab.test.uni-giessen.de/help/public_access/public_access.md#public-access){:target="_blank"}.


## User roles in projects {#project_roles}

When adding project members you have to assign them a designated role:
You can pick either *Guest*, *Reporter*, *Developer*, *Maintainer* or *Owner*.
Each role is associated with an increasing set of permissions, see also the [official documentation](https://gitlab.test.uni-giessen.de/help/user/permissions.md#project-members-permissions){:target="_blank"}.
For projects in the namespace of a group, the group members will get the respective [group role](#group_roles); e.g. a *Guest* in the group will also be a *Guest* in all group projects, unless it is overwritten by individual project roles.
<!-- NOTE: Let's below exclude the permissions from subscription plans STARTER, PREMIUM, ULTIMATE that are not part of the Community Edition. -->

### Permissions as *Guest* {#project_guest}

The *Guest* role is for not-active members who can only read some content, and open issues and leave comments.

Project members with the *Guest* role can
download the project,
leave comments,
view and pull project files,
view wiki pages,
create new issues,
see related issues,
create confidential issues,
and view self-created confidential issues.
If *Public pipelines* is enabled in *Project Settings > CI/CD*, they can also
see a list of jobs,
see a job log,
and download and browse job artifacts.

### Permissions as *Reporter* {#project_reporter}

The *Reporter* role is for members who get more insights and can work in the issue tracker.
Project members with the *Reporter* role get the following permissions in addition to the *Guest* role:

Regarding issues,
*Reporters* can assign and
label issues,
lock issue threads,
and manage the issue tracker and labels.
*Reporters* can also create code snippets,
see a commit status,
see a container registry,
see environments,
see a list of merge requests,
view project statistics,
and view the Error Tracking list.
<!-- NOTE: The error tracking list is part of Operations (de:"Vorgänge"), and you have to integrate with a Sentry server. -->

### Permissions as *Developer* {#project_developer}

The *Developer* role is for members who actively contribute, and have access to everything to go from an idea to its execution, unless something has been explicitly restricted (e.g. through branch protection).
Project members with the *Developer* role get the following permissions in addition to the *Reporter* role:

In the repository, *Developers* can create new branches,
and push to, or remove non-protected branches.
Regarding merge requests, they can create new ones,
manage/accept,
assign and label existing ones,
and lock merge request threads.
They can create new environments and stop them.
Further, *Developers* can cancel and retry jobs,
create or update commit status.
They can update a container registry, or
remove a container registry image.
In the issue tracker, they can create/edit/delete project milestones, and add tags.
They can apply code change suggestions,
create and edit wiki pages, and
rewrite/remove Git tags.

### Permissions as *Maintainer* {#project_maintainer}

The *Maintainer* role is for members who manage a project and its members.
Project members with the *Maintainer* role get the following permissions in addition to the *Developer* role:

*Maintainers* can add new project members,
use environment terminals,
enable/disable branch protection,
push to protected branches,
turn on/off protected branch push for *Developers*,
enable/disable tag protections.
*Maintainers* can edit the project settings,
add deploy keys to the project,
and configure project hooks.
They can manage Runners,
manage job triggers,
and manage environment variables.
If GitLab Pages is activated, they can manage and delete them,
and manage their domains and certificates,
They can manage clusters,
edit comments posted by any user,
manage Error Tracking,
and delete wiki pages.
<!-- "view project Audit Events": Not available in CE... -->

### Permissions as *Owner* {#project_owner}

Users with the *Owner* role control all aspects of a project, including its removal.
In personal projects (within the namespace of a user), exclusively that user has the *Owner* role.
In group projects (within the namespace of a group), multiple *Owners* may exist, if multiple group members are *Owners* as their [group role](#group_roles).
Project members with the *Owner* role get the following permissions in addition to the *Maintainer* role:

*Owners* can switch the [visibility](#project_visibility) of the project,
transfer the project to another namespace,
remove the project,
delete issues,
and disable notification emails.

Note that according to the [terms of service of JLU GitLab]({{ '/terms-of-service/' | relative_url }}), *Owners* are held responsible for all content in their projects, even it came from other users.


## User groups {#group}

All users can create *groups* to organize multiple projects and people.
Note that [data you contribute to a group project will not be deleted]({{ '/information/#deletion_userdata' | relative_url }}) when you [leave the university]({{ '/information/#leaving_JLU' | relative_url }}) or [delete your account](#deletion_account), as long as the [group has at least one member]({{ '/information/#deletion_groups' | relative_url }}).

The access permissions of a project within the namespace of a group depend on the group's [visibility](#group_visibility) and [user roles](#group_roles).
Additionally, individual users from outside of the group can be added as members to individual group projects.

### Visibility of groups {#group_visibility}

Like the [visibility of projects](#project_visibility), the visibility of a group can be set to 1) *private*, 2) *internal*, or 3) *public* to allow access to 1) explicitly selected users, 2) all logged-in users, or 3) any person, including those without a user account.
[Please read here]({{ '/information/#potential_users' | relative_url }}) what the visibility levels *internal* and *public* mean in the case of JLU GitLab.

### User roles in groups {#group_roles}

If you include users as a group member, you also have to assign them a designated role:
Like the [roles for project members](#project_roles), you can pick either *Guest*, *Reporter*, *Developer*, *Maintainer* or *Owner*.
The group role of a member determines the permissions of the equivalent [project role](#project_roles) for all group projects.
In addition, the project role of a member can be adapted individually for each project.

Each group role is associated with an increasing set of permissions about the group itself, see also the [official documentation](https://gitlab.test.uni-giessen.de/help/user/permissions.md#group-members-permissions){:target="_blank"}:
<!-- NOTE: Let's below exclude the permissions from subscription plans STARTER, PREMIUM, ULTIMATE that are not part of the Community Edition. -->

*Guests* can only browse the group, and not change anything.

*Reporters* can additionally manage group labels.

*Developers* can additionally create projects in the group,
and can create/edit/delete group milestones.

*Maintainers* can additionally create sub-groups.

*Owners* can additionally edit the group settings,
manage group members,
remove the group,
view group Audit Events,
and disable notification emails.

Note that according to the [terms of service of JLU GitLab]({{ '/terms-of-service/' | relative_url }}), *Owners* are held responsible for all content in their projects, even it came from other users.

## Settings concerning private information {#settings_privacy}

TODO: Describe setting of commit name and email address (in GitLab and locally), hiding of activity and profile, changing username?, ...


## Last steps {#last_steps}

Before you [leave the university]({{ '/information/#leaving_JLU' | relative_url }}) or [delete your account](#deletion_account), you may consider some options to keep your data, or hand it over to other users, because if your account gets deleted, also [all your personal projects will be deleted]({{ '/information/#deletion_userdata' | relative_url }}).

For example, you may want to synchronize all important Git repositories from JLU GitLab to your computer, to prevent data loss.

To prevent deletion of a personal project in your own namespace, you could transfer it into the namespace of another user or of a group.
This must be coordinated with the new *Owners*.

You could also export projects; this allows you to migrate (nearly) all their data to another GitLab instance.
Unlike the mere synchronization of the Git repositories, this will include the issue trackers, wikis, etc.


## How to delete my account? {#deletion_account}

You can delete your account at any time, by navigating to [*Settings > Account > Delete account*](https://gitlab.test.uni-giessen.de/profile/account) in your browser and confirm with your password.

Before you delete your account, please read this [overview what data will be deleted]({{ '/information/#deletion_userdata' | relative_url }});
just a few [last steps](#last_steps) could spare you possible annoyances.

Note that you cannot immediately delete your account if you are the only *Owner* of a group.
In this case, you must give the *Owner* role to at least one other member, or delete the group in question (e.g. if you are the only remaining member).


## Further help {#more_help}

TODO: More useful links, maybe with explanations. GitLab itself has a bunch more.

- [The official user help for JLU GitLab](https://gitlab.test.uni-giessen.de/help/user/index.md){:target="_blank"}.
- [Free online book *Pro Git*](https://git-scm.com/book/){:target="_blank"}