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)

## Essential 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 where edits are tracked into a history of versions/snapshots.
  You can manage multiple separate repositories.
- A *commit* is a 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 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 potentially private settings.
- A *branch* a named subset of snapshots to keep the repository neat and tidy.
- The Git commands *pull* and *push* synchronize branches of Git repositories in different locations (such as 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.
  In addition, GitLab offers multiple systems to automatically execute source code within the project, e.g. to run tests or to generate a website.
- Every project is assigned to a *namespace*.
  Every user and every group has their own namespace.
  The read and write access of a project depends on its [visibility](#visibility_projects) and your own [role as project member](#user_roles), or alternatively the visibility and role settings of the [group](#groups) in who's namespace it resides.
- With a *merge request* you can ask to transfer/merge one or multiple commits from one Git repository into another.

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

## 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]({{ '/information/#potential_users' | relative_url }}) what this means in the case of JLU GitLab.
- Projects with *public* visibility are also visible for people without a user account.
  [Please read here]({{ '/information/#potential_users' | relative_url }}) what this means 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 {#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.
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* {#role_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:

They can add new team 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 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,
delete wiki pages,
and view project Audit Events.

### 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 with explanations?

- [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"}