en_help.md

---
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. -->
- [Necessary terms](#necessary_terms)
- [How to use GitLab?](#how_to_gitlab)
- [First steps](#first_steps)
- [Visibility of projects](#visibility_projects)
- [User roles in projects](#user_roles)
    - [Permissions as *Guest*](#role_guest)
    - [Permissions as *Reporter*](#role_reporter)
    - [Permissions as *Developer*](#role_developer)
    - [Permissions as *Maintainer*](#role_maintainer)
    - [Permissions as *Owner*](#role_owner)
- [User groups](#groups)
- [Settings about private information](#private_info)
- [Last steps](#last_steps)
- [Further help](#more_help)

## Necessary terms {#necessary_terms}

Git and GitLab are versatile tools with many technical concepts and terms.
Because their development and terminology is created in English, they are currently only partly translated into other languages.
To keep the following help entries (e.g. regarding read- and write access) short and comprehensible, the essential technical 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 {#necessary_terms_git}

- A Git *repository* denotes a collection of files and folders that are tracked into a history of snapshots.
  You can manage multiple separate repositories.
- A *Commit* is a certain Schnappschuss of the data in the repository.
  Upon creation of a commit, the set name, email address, date, time and an arbitrary comment become indivisibly connected to the new snapshot.
  This is a fundamental security feature of Git, to prevent future changes of this snapshot.
  Read [here](#private_info) how to change these private settings.
- A *branch* a certain sub-history of snapshots, i.e. a part of a Git repository.
- The Git commands *pull* and *push* synchronize a branch of a Git repository between 2 locations (e.g. between your own computer and JLU GitLab).

### GitLab terminology {#necessary_terms_gitlab}

- A project on (JLU) GitLab contains a Git-Repository, and offers many additional functions to manage it.
- Every project is assigned to a *namespace*.
  All users and groups have their own namespace to keep projects.
  The read and write access depend on the [visibility of the project](#visibility_projects) and your own [role as project member](#user_roles), or alternatively the visibility and role settings of the [group](#groups) in question.
- With a *merge request* you can ask others to transfer/merge one or multiple commits from one Git repository into another repository.

## 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 (without 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)).

## Visibility of projects {#visibility_projects}

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](#user_roles)).

- Projects with *private* visibility are only visible to the [members of the project](#user_roles).
- Projects with *internal* visibility are visible to anyone with a user account who is logged in.
  [Please read here what this means in the case of JLU GitLab]({{ '/information/#potential_users' | relative_url }}).
- Projects with *public* visibility are also visible for people without a user account.
  [Please read here what this means in the case of JLU GitLab]({{ '/information/#potential_users' | relative_url }}).

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 {#user_roles}

If you include other users as a project member, you also 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"}.
<!-- NOTE: For simplicity, let's below exclude the permissions from subscription plans STARTER, PREMIUM, ULTIMATE; assuming that they are not part of Community Edition. -->

### Permissions as *Guest* {#role_guest}

The *Guest* role is for not-active members who can only some read 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* {#role_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,
they 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* {#role_developer}

The *Developer* role is for members who directly 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, they 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.
*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* {#role_maintainer}

TODO 
<!-- Maintainers are super-developers: they are able to push to master, deploy to production. This role is often held by maintainers and engineering managers. -->

### Permissions as *Owner* {#role_owner}

TODO 
<!--
Owners are essentially group-admins.
They can give access to groups and have destructive capabilities.
-->

## User groups {#groups}

TODO: Group members and their roles and associated permissions.

TODO: Clarification that group projects won't be deleted when leaving JLU, as long as members exist in the group.

[Similar to the visibility of projects](#visibility_projects), the visibility of groups can be set to *private*, *internal*, or *public* to allow access to explicitly selected users, all logged-in users, or any person even without a user account.

## Settings about private information {#private_info}

TODO: Setting of commit email address (in GitLab and locally), hiding of activity and profile, ...

## Last steps {#last_steps}

TODO: Explanation when and what stuff gets deleted once you leave JLU (account data, *own* projects, ...) and what doesn't (group projects including issues and comments, commits, ...).
Except for commits, stuff will be anonymized (transferred to the Ghost user).

## Further help {#more_help}

TODO: More useful links, maybe in categories.

- The official user help for JLU GitLab, <https://gitlab.test.uni-giessen.de/help/user/index.md>
- Free online book *Pro Git*, <https://git-scm.com/book/>