GitLab

The GitLab resource type enables you to manage metadata for GitLab repositories in Coscine.

Background

• Allows data in GitLab projects to be tagged with metadata
• Advantage: linking of files with metadata in Coscine
• Security and accessibility of data depends on external provider. As a resource creator it is up to you to ensure that all members of the project follow the terms of use and privacy policy of the underlying storage provider.

Set up a GitLab resource

• Select GitLab when creating a resource in step 1
• Specify the GitLab instance domain name (e.g. "https://git.rwth-aachen.de/")
• Fill in the GitLab project or group access token (see GitLab - project access token and GitLab - group access token)
  • New Access Tokens can be created via the settings in GitLab. Access to the resources in Coscine will later be possible according to the selected authorizations of the Gitlab token.
  • Token is created and can be copied to resource creation page.
• Verify the GitLab connection by pressing the blue button
• Select the GitLab project and the project branch
• Accept that you adhere to the terms of use and privacy policy of the underlying storage provider. Since the storage provider may differ between instances (institutions can run their own GitLab instance), you need to figure out the specific guidelines of the provider that you have specified in the domain field.

Figure 1 - GitLab resource setup

Using a GitLab resource

• All files that are also contained in the GitLab project are displayed in a Coscine GitLab resource.
• Depending on the settings of the token created, files can be uploaded or deleted via Coscine in the corresponding GitLab project. The reverse is also true, i.e. all uploaded files in GitLab are also displayed in Coscine, etc.
• In addition, the metadata for the individual files can be entered in a GitLab resource, as in other Coscine resources.

Warning

The defined roles and scopes of the GitLab token influence the extent to which file access is possible (e.g. read only or editing possible etc.). The Coscine user administration (owner, member and guest) influences who is granted file access. If the people in your GitLab project do not correspond to the members of the Coscine project, please keep this in mind.

Archiving a GitLab resource

A GitLab resource can be set to archived. This archives all metadata entered for the files in Coscine. Your GitLab project will not be archived as a result.

Storage space for GitLab resource

This resource type does not require any storage space, since data is not stored in Coscine.

GitLab token

A GitLab access token is a tool used for authentication that grants a programme or service certain access rights to a GitLab project or group, eliminating the need for users to log in with a username and passowrd.

Use of GitLab token

Coscine uses the GitLab token to integrate GitLab projects as resources. Specifically, this means that:

• You can select a GitLab project in Coscine and then display its files.
• Depending on the tokens's permissions, you can upload, delete or modify files.
• In addition, you can capture and maintain metadata for these files via Coscine. This includes information about the file, version and tags, which is then linked to the files in the GitLab project.

Permissions of the GitLab token

To ensure seamless communication between Coscine and GitLab, it is essential that the token possesses specific permissions, also referred to as scopes. Users can create access token to grant permissions at group and project level (for example, for documentation). To create an access token, users must navigate to Setting > Access Token. This option is only visible to users with Owner permissions in GitLab.

Figure 2 - Permissions of the GitLab Token

GitLab token role

When considering the token's function, approach it in the same way you would with a user token. The same roles apply in this case. In short, the role determines what the token is allowed to do.

This setting can be overridden by server administration on self-hosted GitLab instances (e.g. RWTH's GitLab). Therefore, if you are not using the default gitlab.com instance, the settings may differ.

Figure 3 - GitLab Token Scopes

Warning

The api scope is mandatory. This means that the token must be authorized to work via the GitLab API. This enables Coscine to perform all the necessary actions, such as reading and writing files.

A user with the following rights in your GitLab instance is allowed to do the following:

• Read projects from groups (Guest)
• Read files from a project (Guest)
• Write or commit to branches in project (Developer)

Figure 4 - GitLab Token Roles

Warning

Please note that this information may vary depending on your GitLab configuration. As a general rule, we recommend assigning the role of Maintainer or at least Developer to the token. However, as a rule of thumb, choose the token role as you would if Coscine were a regular user in your GitLab group/project.