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?

There are two major ways to use the various functions of GitLab.

Working via web browser is particularly convenient: For example, you can read content, comment on issues, edit wiki pages, and also edit files in the Git repository via the [web editor](https://docs.gitlab.com/ee/user/project/repository/web_editor.html) or the [Web IDE](https://docs.gitlab.com/ee/user/project/web_ide/).

For more extensive changes, it is recommended to work on a local copy of a Git repository.
For this you need Git on your computer to keep your local copy in sync with the one on GitLab (via Git `pull` and `push`).
Most common programming software (like Matlab or RStudio) support working with a local Git repository.
To synchronize your changes with JLU GitLab you need to [connect](#how-to-connect-to-jlu-gitlab) and [authenticate yourself](#how-to-authenticate-to-jlu-gitlab).


## How to connect to JLU GitLab?

JLU GitLab is accessible via two network protocols: via `HTTPS` or via `SSH`.
Each application (such as web browser, Git, etc.) must use one of these protocols.

Connections via HTTPS are recommended and are possible directly from the Internet.
HTTPS provides access to all GitLab features (Git-over-HTTP and GitLab APIs).
Authentication is possible via [JLU access data](#authentication-with-jlu-credentials) (insecure and inflexible) or via [Access Token](#authentication-with-access-token) (secure and flexible).

Connections via SSH are only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn).
SSH only provides synchronization of Git repositories, no other GitLab functions.
For authentication you need [an SSH key](#authentication-with-ssh-key).

Beware to select the URL with your desired connection type when you _clone_ a Git repository:

![Screenshot Clone Button Menu](../images/git-clone-choose-protocol.png)


## How to authenticate to JLU GitLab?

To gain access to your GitLab account or your projects, you need to [authenticate](https://en.wikipedia.org/wiki/Authentication) to JLU GitLab.

To [register your account](#how-to-register-an-account), you will need to log in once via browser using your JLU credentials.
Once you have an account, there are several authentication methods you can choose from.

Here are 3 methods of authentication compared to help weigh security and usability.
Spoiler: The recommended method is [authentication with a (personal) access token](#authentication-with-access-token) as soon as the functions in the browser are no longer sufficient for you.

- By [JLU credentials (identifier and password)](#authentication-with-jlu-credentials).
- By [(personal) access token](#authentication-with-access-token).
- By [SSH key](#authentication-with-ssh-key).

Here is an overview of the main pros and cons; explanations can be found below.

| Method                | Recommended | Usable with 2FA | Usable without VPN | Flexible management |
|-----------------------|-------------|-----------------|--------------------|---------------------|
| JLU credentials       | No          | Yes             | No                 | No                  |
| Personal Access Token | Yes         | Yes             | Yes                | Yes                 |
| SSH key               | Partial     | No              | No                 | Partial             |


### Authentication with JLU credentials

When [connecting via HTTPS](#how-connect-with-jlu-gitlab) (e.g. via web browser or Git), you can authenticate yourself with your personal JLU identifier and JLU password.

The only __advantage__ of this method is its simplicity.

An important __disadvantage__ of this method is its potential for damage:
In JLU GitLab, your JLU credentials are _always_ associated with _all_ your permissions, including deleting your data and usage account.
This can lead to the greatest possible damage in the event of user error or password theft.
Even outside of JLU GitLab, your JLU credentials are particularly worth protecting, as they are used as a "master key" for many JLU IT systems (e.g. email access).
If you lose your JLU password, you will no longer have access yourself (temporarily).

For flexible, restricted access, especially for (automatic) access from multiple devices, it is recommended to [use access tokens](#authentication-with-access-token) instead of your JLU credentials.

For higher security against theft of your JLU password, you can enable [two-factor authentication (2FA)](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html) in JLU GitLab.
Note that if you enable 2FA for [Git-over-HTTPS](#how-connect-to-jlu-gitlab), you must create and use a [personal access token](#authentication-with-access-token).

### Authentication with access token

An *access token* is a string of random characters, generated by JLU GitLab, with associated permissions that you can use in place of your JLU credentials.
Using access tokens requires a [connection via HTTPS](#how-to-connect-to-jlu-gitlab).

__Advantages__ of this method include the separation of your sensitive JLU credentials and the flexibility of permissions by purpose.
These can limit the damage in the event of theft, loss, or user error.

The __disadvantages__ are the required setup and familiarization, which should be simplified by the following help texts for [creating](#creating-a-personal-access-token) and [securely storing and using](#securely-storing-and-using-access-tokens) (personal) access tokens.

A [personal](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) access token (PAT) allows permissions to all areas of your GitLab account (Git-over-HTTPS and API).
If you want to use [2-factor authentication](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html) for more security, you need to create and use a PAT for authentication over HTTPS (see below).

In addition to _personal_ access tokens, there are also tokens for [projects](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) and [user groups](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html).
They are used analogously to a personal token, but allow more fine-grained restrictions to individual projects or groups.

#### Creating a personal access token

To create a personal Access Token (PAT), log in via browser, click on your profile in the upper right corner, select *Edit profile* and then *Access Tokens* in the left side menu.
Alternatively, you can click on [this direct link](https://gitlab.ub.uni-giessen.de/-/profile/personal_access_tokens).

Note that you can create multiple PATs for different purposes; for example, one for your laptop and another one with fewer permissions and earlier expiration date for a lab computer.

To create a PAT:

1. For __Token name__ choose an appropriate name for the token, for example the name of the device for which the token is intended.
2. If possible, assign an expiry date for the validity of the token under __Expiry date__.
   This consideration depends on the intended purpose.
3. Allow the required permissions for the intended purpose of the token;
   for example __write\_repository__ is sufficient for read and write access to all your Git repositories.
   An overview of possible permissions can be found [here](https://gitlab.ub.uni-giessen.de/help/user/profile/personal_access_tokens.md#personal-access-token-scopes).
4. Click *Create personal access token*:
   Now the unique random string of the new token is displayed, for example `aztGzZkCT-kGyRs1M6x1`.
   Since the string is displayed only immediately after creation, you should [save it securely for use (see below)](#securely-storing-and-using-access-tokens) immediately.

#### Securely storing and using access tokens

To use an access token, it must be available for each connection to GitLab.
Rather than repeatedly typing it or storing it unsecured, the following recommended method is to store a token in an encrypted storage.
<!--
Note: Insecure storage is also possible; make sure your Git configuration meets your security needs.
Because of the encryption used, this method is only useful for interactive work.
(And since automated access requires further knowledge and consideration anyway, it will not be discussed further here).
-->

##### Requirement: Encrypted store for Git credentials

Current Git versions support encrypted storage of your login credentials.
Depending on the operating system, encryption is implemented by different utilities.

When installing the current, [official Git client](https://git-scm.com/) on _Windows_ or _macOS_, secure defaults are set that use the native encrypted store.
In this case, no configuration is required from you.
You can view and modify the configured utility via `git config credential.helper`; the default secure setting for Windows is `manager-core`, for macOS `osxkeychain`.

For _Linux_, or if you want to use _multifactor authentication_, the [*Git Credential Manager (GCM)*](https://github.com/GitCredentialManager/git-credential-manager#git-credential-manager) utility is recommended.
On Linux, after [installing and configuring *GCM*](https://github.com/GitCredentialManager/git-credential-manager#linux), you also need to decide on a [*credential store*](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/credstores.md#credential-stores), for example *SecretService*, via `git config --global credential.credentialStore secretservice`.

##### Securely storing and using tokens

If the [requirement for secure storage](#requirement-encrypted-store-for-git-credentials) is met and you have [created a token](#creating-a-personal-access-token), only two steps remain to use the token:

1. Start any Git action from your device that requires authentication to GitLab via HTTPS; for example, read access to a private project via `git pull` or `git clone`.
   Be sure to use an HTTPS URL that starts with `https://` (if in doubt, check the configured Git remote URL).
2. Enter your new token *in place of your password* when asked for your login data:
    - As username, enter your JLU identifier.
    - For the password, enter the token's string you received during [creation](#creating-a-personal-access-token), for example `aztGzZkCT-kGyRs1M6x1`.

Here is a screenshot of the expected dialog box of Windows 10:

![Windows 10 dialog git help program manager-core](../images/dialog-win10-manager-core.png)


### Authentication with SSH key

Note that access via SSH is only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn).

The __advantages and disadvantages__ of this method hover between the insecure and inflexible use of your HRZ credentials and the more secure and flexible [authentication via access token](#authentication-with-access-token).

To create an SSH key pair there are [instructions in the book *Pro Git*, chapter 4.3](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key).
Afterwards you have to deposit the public(!) key to your JLU GitLab account.
Read for example [this documentation](https://gitlab.ub.uni-giessen.de/help/ssh/index.md#add-an-ssh-key-to-your-gitlab-account).


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