Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • work-in-progress
2 results
Blame Permalink
Help.md 25.64 KiB

Help

This page offers you some introductory information on how to use JLU GitLab, but it cannot replace the official user help. For specific information about JLU GitLab, see information.

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 provides a collection of links for you to familiarize yourself with these concepts.

Git terminology

  • 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 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 and, if you are a project member, your role in the project. For group projects, the permissions depend further on the group's visibility and, for group members, on their role in the group.

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 or the 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 and authenticate yourself.

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 (insecure and inflexible) or via Access Token (secure and flexible).

Connections via SSH are only possible via VPN. SSH only provides synchronization of Git repositories, no other GitLab functions. For authentication you need an SSH key.

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

Screenshot Clone Button Menu

How to authenticate to JLU GitLab?

To gain access to your GitLab account or your projects, you need to authenticate to JLU GitLab.

To register your 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 as soon as the functions in the browser are no longer sufficient for you.

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 (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 instead of your JLU credentials.

For higher security against theft of your JLU password, you can enable two-factor authentication (2FA) in JLU GitLab. Note that if you enable 2FA for Git-over-HTTPS, you must create and use a personal 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.

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 and securely storing and using (personal) access tokens.

A personal 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 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 and user groups. 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.

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

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 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) utility is recommended. On Linux, after installing and configuring GCM, you also need to decide on a credential store, for example SecretService, via git config --global credential.credentialStore secretservice.

Securely storing and using tokens

If the requirement for secure storage is met and you have created a 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, for example aztGzZkCT-kGyRs1M6x1.

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

Windows 10 dialog git help program manager-core

Authentication with SSH key

Note that access via SSH is only possible via 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.

To create an SSH key pair there are instructions in the book Pro Git, chapter 4.3. Afterwards you have to deposit the public(!) key to your JLU GitLab account. Read for example this documentation.

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 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. To login, go to https://gitlab.ub.uni-giessen.de/ and enter your JLU user ID (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 (in German); your account be registered only after you agree to it.

Screenshot JLUGitLab account creation

First steps

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

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

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

  • Projects with private visibility are only visible to the members of the project. For group projects, this includes the group members, depending on their role.
  • Projects with internal visibility are visible to anyone with a user account who is logged in. Please read here which people are included.
  • Projects with public visibility are visible for people without a user account who can access JLU GitLab. Please read here which people are included.

For more details, please refer to the official documentation.

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. For projects within the namespace of a group, the group members will get the respective group role; e.g. a Guest in the group will also be a Guest in all group projects, unless that is overwritten by individual project roles.

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.

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.

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. Project members with the Owner role get the following permissions in addition to the Maintainer role:

Owners can change the 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, 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 when you leave the university or delete your 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 and user 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, 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 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, you can pick either Guest, Reporter, Developer, Maintainer or Owner. The group role of a member determines the permissions of the equivalent project role 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:

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, 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 or delete your account, 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 in your browser and confirming with your password.

Before you delete your account, please read this overview on what data will be deleted; just a few 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.