Help.md

# Help

This page offers you some introductory information on how to use JLU GitLab, but it cannot replace the [official user help](https://gitlab.ub.uni-giessen.de/help/user/index.md).
For specific information about JLU GitLab, see [information](Information.md).

[[_TOC_]]


## Important concepts

Git and GitLab are versatile tools using many technical concepts and terms.
As both are developed and created in English-speaking environments, these concepts and terms have been only partially translated into other languages.
To keep the following list of helpful information (e.g. regarding read and write permissions) short and comprehensible, the essential terms are explained in plain English.
This is only a well-intended overview; [further help](#further-help) provides a collection of links for you to familiarize yourself with these concepts.

### Git terminology

- [*Git*](https://en.wikipedia.org/wiki/Git) is a software for version-controlling files.
- A *repository* is a collection of files, which depicts edits of those files as a history of snapshots.
  Using Git, you can manage as many separate repositories as you want.
- A *commit* is a snapshot of the data in the repository.
  When you create a commit, the configured email address, name, date, time and a random comment become inseparably 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 that has been given an arbitrary name, and which 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).
  As soon as two branches are synchronized, both of them contain a copy of all data, i.e. the full history of snapshots.

### GitLab terminology

- 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 the *namespace* of an individual user or a group of users.
  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 for a project depend indirectly on its namespace:
  For projects within the namespace of other users, your permissions depend on the [project's visibility](#visibility-of-projects) 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](#visibility-of-groups) and, for group members, on [their role in the group](#group_roles).
<!-- NOTE, unnecessary?: - Using a *merge request* you can ask to merge one or multiple commits from one Git repository into another one. -->


## How to use GitLab?

- TODO: Using the browser is sufficient for many small issues, but for more serious work you should install Git locally.
- TODO: Many of the most common scientific softwares such as MATLAB, RStudio, etc. have integration with Git.

Please note that access from the Internet is restricted to HTTPS; access via SSH is only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn/).

## How to register an account?

To create an account for JLU GitLab, an existing JLU account (g-, s-, n-, or j-) is required.
Please refer to [this page](https://www.uni-giessen.de/faculties/svc/it/index_html/userid/useraccounts?set_language=en) for information on JLU accounts.

If you have a JLU account, your account for JLU GitLab will be registered upon your first login, if you agree to the [Terms of Use](TermsOfUse.md).
To login, go to https://gitlab.ub.uni-giessen.de/ and enter your [JLU user ID](https://www.uni-giessen.de/faculties/svc/it/index_html/userid) (g-, s-, n-, or j- account) into the field **JLU (g-/s-/n-/j-) Username** and your corresponding, personal password into the field **Password**.

Upon your first login, you will be prompted with the [Terms of Use](TermsOfUse.md) ([in German](../de/Nutzungsbedingungen.md)); your account be registered only after you agree to it.

![Screenshot JLUGitLab account creation](../images/help-login.png)


## First steps

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

- You can choose another language at [Einstellungen > Profil > Einstellungen > Lokalisierung](https://gitlab.ub.uni-giessen.de/profile/preferences#localization). But as GitLab uses many untranslatable terms, there might still be many English terms, despite different language settings.

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

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-in-projects)).

- Projects with *private* visibility are only visible to the [members of the project](#user-roles-in-projects).
  For group projects, this includes the [group members](#user-roles-in-groups), depending on their role.
- Projects with *internal* visibility are visible to anyone with a user account who is logged in.
  [Please read here](Information.md#who-may-use-jlu-gitlab) which people are included.
- Projects with *public* visibility are visible for people without a user account who can access JLU GitLab.
  [Please read here](Information.md#who-may-access-jlu-gitlab) which people are included.

For more details, please refer to the [official documentation](https://gitlab.ub.uni-giessen.de/help/public_access/public_access.md#public-access).


## User roles in projects

When adding project members you have to assign them to a designated role:
You can pick either *Guest*, *Reporter*, *Developer*, *Maintainer* or *Owner*.
Each role entails an increasing set of permissions, see also the [official documentation](https://gitlab.ub.uni-giessen.de/help/user/permissions.md#project-members-permissions).
For projects within the namespace of a group, the group members will get the respective [group role](#user-roles-in-groups); e.g. a *Guest* in the group will also be a *Guest* in all group projects, unless that 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*

The *Guest* role is for non-active members who can only read some content, and open and comment on tickets.

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*

The *Reporter* role is for those members who get more insights and who work with the issue tracker.
In addition to those of the *Guest* role, project members assigned to the *Reporter* role have the following permissions:

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 the 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 connect to a Sentry server. -->

### Permissions as *Developer*

The *Developer* role is for members who actively contribute, and have access to everything throughout the entire project process, unless something has been explicitly restricted (e.g. by branch protection).
In addition to those of a *Reporter* role, project members assigned to the *Developer* role have the following permissions:

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

### Permissions as *Maintainer*

The *Maintainer* role is for members who manage a project and its members.
In addition to those of the *Developer* role, project members assigned to the *Maintainer* role have the following permissions:

*Maintainers* can add new project members,
use environment terminals,
enable/disable branch write protection,
`push` to protected branches,
turn on/off write-protected branch push for *Developers*,
enable/disable tag write 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*

Users assigned to the *Owner* role control all aspects of a project, including its removal.
In personal projects (within the namespace of a user), that user exclusively 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 change the [visibility](#project_visibility) of the project,
transfer the project into another namespace,
remove the project,
delete issues,
and disable notification emails.

Note that according to the [terms of service of JLU GitLab](TermsOfService.md), all *Owners* are held responsible for the content of their projects, even if it originates from other users.


## User groups

All users can create *groups* to organize multiple projects and people.
Note that the [data you contribute to a group project will not be deleted](Information.md#what-happens-to-my-data-when-my-account-is-deleted) when you [leave the university](Information.md#what-happens-when-i-leave-jlu) or [delete your account](#how-to-delete-my-account), as long as the group has at least one member remaining.

The access rights to 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

Like the [visibility of projects](#visibility-of-projects), 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.md#who-may-use-jlu-gitlab) what the visibility levels *internal* and *public* mean in the case of JLU GitLab.

### User roles within groups

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

Each group role entails an increasing set of permissions within the group, see also the [official documentation](https://gitlab.ub.uni-giessen.de/help/user/permissions.md#group-members-permissions):
<!-- 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, but not change anything.

*Reporters* can additionally manage group labels.

*Developers* can additionally create projects within the group,
and they 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 use for JLU GitLab](TermsOfUse.md), all *Owners* are held responsible for the content of their projects, even if it originates from other users.

## Settings concerning private information

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


## Last steps

Before you [leave the university](Information.md#what-happens-when-i-leave-jlu) or [delete your account](Information.md#what-happens-to-my-data-when-my-account-is-deleted), you may consider some options to keep your data, or to hand it over to other users. This is because if your account gets deleted, all your personal projects will be deleted as well.

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

So as not to delete a personal project within your own namespace, you can transfer it into the namespace of another user or of a group.
This has to be coordinated with the new *Owners*.

You can also export projects; this will allow you to migrate (nearly) all related data to another GitLab instance.
Unlike merely synchronizing Git repositories, this will include issues, wikis, etc.


## How to delete my account?

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

Before you delete your account, please read this [overview on what data will be deleted](Information.md#what-happens-to-my-data-when-my-account-is-deleted);
just a few [last steps](#last-steps) can spare you future trouble.

Note that you cannot immediately delete your account if you are the only *Owner* within a group.
In this case, you have to assign 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

TODO: More useful links, maybe sorted into categories. GitLab itself has a bunch more.

- [The official user help for JLU GitLab](https://gitlab.ub.uni-giessen.de/help/user/index.md).
- [Free online book *Pro Git*](https://git-scm.com/book/)