GitLab Developer FAQ: Difference between revisions

Revision as of 22:29, 9 February 2021

Main Page -> Documentation -> Gitlab Developer FAQ

This is a collection of frequently asked Gitlab questions for developers

Please edit this page and add your question, or send email to pCT@uib.no

Authentication

In order to clone non-public repositories and do synchronization, an authentication method is required. It is recommended to use SSH keys

Register SSH key

Login to https://git.app.uib.no
go to User settings -> SSH Keys (https://git.app.uib.no/-/profile/keys)
paste public SSH key from your .ssh folder, something like id_*.pub
select optionally a title and expiration date
click Add

Create access token

Login to https://git.app.uib.no
go to User settings -> Access Tokens (https://git.app.uib.no/-/profile/personal_access_tokens)
Choose name and expiration date and scopes
click Create personal access token
Store the token in a safe place or configure the relevant application for accessing the repository with this token immediately

Hints:

Create access tokens only for the scope with the minimal access permissions required for your purpose
Keep in mind: the token is only visible in the web interface after creation, you can not get it later
Unused tokens should be revoked as soon as possible

Create repository clone

A repository clone is your work copy, it is created using the git clone-command.

Find the links for the repository to be cloned

Clone using SSH

An SSH key needs to be configured -> Gitlab Developer FAQ#Register SSH key

  git clone git@git.app.uib.no:pct/pct-online.git

Note: this is an example for the pct-online repository

Clone using Access Token

An access token needs to be configured -> Gitlab Developer FAQ#Create access token

   git clone https://gitlab-ci-token:your-token-number@git.app.uib.no/pct/pct-online

Note: insert your token number

Working with forks

What is a fork?

Every logged-in user can access the main repository, however only a small group of administrators has write access. To contribute, a user creates a fork (see here) from the repository. This is a repository copy in the GitLab system where a single developer or a group of developers have full access. The fork is created in a user space.

It's important not to be confused by the terminology. In contrast to the fork which is still a remote repository on the GitLab web service, a local copy of the repository is required on the working machine in order to work on the project. This copy is referred to be a clone (see here).

How do I create a project fork?

A project fork or repository fork is a copy of the original repository where a user or a group of users has/have full control. All development in our project is carried out in the individual forks. Branches of project forks are merged back into the main repository by merge requests, preferably via fast forward merges. That requires developers to rebase project forks to the main repository and resolve all conflicts before requesting a merge.

See How to fork a project for some general introduction.

In the pCT project you can create a fork of all the main repositories in the GitLab pct group by clicking the fork button.

Note: pct-online is an example, replace by repository you are working with.

Which rules should I obey?

Your repository fork is your sandbox, you can do whatever you want. Still its good to follow some rules, unless you have your own rules at hand right now, you can apply the following:

leave the master branch in sync with the main repository, do not make commits to it
commit your changes to the dev branch
if you start a new feature, and it's expected to take a while, make a feature branch, e.g. dev-feature and give the feature a name
synchronize regularly to the main repository by rebasing (tutorial coming soon)
add your colleagues as developers to share the code with them, or simply add group pct as member.

I have a clone of the main repository and want to connect it now to my fork?

Note: User.Space needs to be replaced by your user space, see the link in the web interface. replace pct-online by repository you are working with.

Check the remotes of your repository

   git remote -v

Should show you something like

   origin	git@git.app.uib.no:pct/pct-online.git (fetch)
   origin	git@git.app.uib.no:pct/pct-online.git (push)

Since origin should refer to your development proxy, we first rename the current origin to upstream:

   git remote rename origin upstream

Add the fork as the new origin:

   git remote add origin git@git.app.uib.no:User.Space/pct-online.git

Synchronize with the fork

   git remote update

Make your branches to track the branches of your fork, e.g. for the dev branch:

   git checkout dev
   git branch --set-upstream-to origin/dev

Check the remotes:

   git remote -v

With new result:

   origin	git@git.app.uib.no:User.Space/pct-online.git (fetch)
   origin	git@git.app.uib.no:User.Space/pct-online.git (push)
   upstream	git@git.app.uib.no:pct/pct-online.git (fetch)
   upstream	git@git.app.uib.no:pct/pct-online.git (push)

@@ Line 49: / Line 49: @@
 == Working with forks ==
-=== I have a clone of the main repository and want to connect it now to my fork ===
+=== What is a fork? ===
+Every logged-in user can access the main repository, however only a small group of administrators has write access. To contribute, a user creates a '''fork''' (see [[Documentation#Creating_a_project_fork | here]]) from the repository. This is a repository copy in the GitLab system where a single developer or a group of developers have full access. The fork is created in a user space.
+It's important not to be confused by the terminology. In contrast to the '''fork''' which is still a remote repository on the GitLab web service,
+a local copy of the repository is required on the working machine in order to work on the project. This copy is referred to be a '''clone''' (see [[Documentation#Making_local_working_copy | here]]).
+=== How do I create a project fork? ===
+A ''project fork'' or ''repository fork'' is a copy of the original repository where a user or a group of users has/have full control. All development in our project is carried out in the individual forks. Branches of project forks are merged back into the main repository by '''merge requests''', preferably via '''fast forward''' merges. That requires developers to rebase project forks to the main repository and resolve all conflicts before requesting a merge.
+See [https://docs.gitlab.com/ce/gitlab-basics/fork-project.html How to fork a project] for some general introduction.
+In the pCT project you can create a fork of all the main repositories in the [https://git.app.uib.no/pct GitLab pct group] by clicking the '''fork''' button.
+[[File:Pct-online-fork-button.png]]
+'''Note''': <span style="color:white; background:green">'''pct-online'''</span> is an example, replace by repository you are working with.
+=== Which rules should I obey? ===
+Your repository fork is your sandbox, you can do whatever you want. Still its good to follow some rules, unless you have your own rules at hand right now, you can apply the following:
+* leave the ''master'' branch in sync with the main repository, do not make commits to it
+* commit your changes to the ''dev'' branch
+* if you start a new feature, and it's expected to take a while, make a ''feature'' branch, e.g. ''dev-feature'' and give the feature a name
+* synchronize regularly to the main repository by rebasing (tutorial coming soon)
+* add your colleagues as developers to share the code with them, or simply add group '''pct''' as member.
+[[File:GitLab-fork-members-illustration.png]]
+=== I have a clone of the main repository and want to connect it now to my fork? ===
 '''Note:''' <span style="color:yellow; background:red">'''User.Space'''</span> needs to be replaced by your user space, see the link in the web interface.
 replace <span style="color:white; background:green">'''pct-online'''</span> by repository you are working with.