GitLab Developer FAQ: Difference between revisions

Revision as of 14:48, 4 March 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

In order to connect to the GitLab service via 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 the external link 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 for working with the fork?

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. To simply allow read access for the project members add group pct with Reporter-role.

select Fast-forward merge for your fork in Settings -> General -> MergeRequests

How can I make a clone of a project in my fork?

Note

The example is using access via SSH
refer to GitLab Developer FAQ#Clone SSH Key and GitLab Developer FAQ#Clone using Access Token for further details.
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.

Procedure

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

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

This is a typical situation. You got a clone of some repository and while using it, you started developing. Now you need to connect the clone with the fork you want to use for contributing to the project.

Note

All the examples are using access via SSH, refer to GitLab Developer FAQ#Clone using Access Token and adjust accordingly.
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.

Procedure

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)

My external user account on GitLab does not give me a namespace for forking

This is a limitation of GitLab, the external users do not get their own namespace and a personal fork is thus not possible.

Instead, you can use a common development fork which is created by the project maintainers in subgroup pct/development. Get in contact with the maintainers to be added with developer role.

The standard branches of forks in this namespace will be protected. Developers can push feature branches which should have a name user_feature. Merge requests can be created in the usual way.

How can I push a feature branch to the common development fork

If you do not have a personal fork and have cloned from the master repository, you can still push your development in a feature branch to the common development forks in pct/development.

Create feature branch if not yet done, since it will be in a common fork, include user name in the branch name
```
git checkout -b user_feature
```

Push to common fork

git push git@git.app.uib.no:pct/development/pct-online.git user_feature

Replace pct-online by repository you are working with.

Note: be extra careful as you are pushing to a common space, especially with forced push.

Working with clones

How many clones can I have?

Since a clone is just a local copy, you can have as many as you want. This is useful if you need to do some testing in a fresh repository or on a different machine.

How can I change the upstream link?

A remote has a name in the git clone, the default name is often origin

Note

The example is using access via SSH
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.
If you are using a different name, replace origin accordingly

Procedure

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

Can I have more than one upstream repository

Yes, as a more advanced option, multiple remote repositories can be added to the clone. All remote repositories are referenced through their names, e.g. origin pointing to the fork and upstream pointing to main repository. this is the recommended setup to work with both the developer fork and synchronize it to the main repository.

Note

The example is using access via SSH
To add the fork of a colleague, replace pct by appropriate user space
Replace pct-online by repository you are working with.
If you want a different name, replace upstream accordingly
After adding the new repository you need to update the remote.

Procedure

git remote add upstream git@git.app.uib.no:pct/pct-online.git
git remote update upstream

How can I publish new development in my fork

All work you are doing with git is primarily within the local clone. Only by pushing updates to the remote repository you make it available for others.

Once you have added commits to e.g. the dev branch, those commits can be pushed upstream to the fork (if origin refers to the fork)

git push origin dev

Or for a feature branch

git push origin dev-cool-feature

This will create a remote branch in the remote repository if not yet there, the corresponding branch in the clone will be set up to track the remote branch. If you have pushed earlier to the remote branch and meanwhile have changed the commit history - a fully valid procedure for development branches - the tip of the remote branch and the local branch have different commit history and you can not add additional commits by simply pushing to the remote. In this case, a forced update is needed and the remote branch is set to the commit history of the local branch. Everything not common will be lost in the remote.

git push -f origin dev

How can I make a backup of a branch

If you are starting to do changes to a branch, e.g. rebasing and resolving conflicts, it's good to make a copy of the branch.

Simply create a new branch from the current one, and

git branch backup_feature

Once you have done the changes, check if there is any difference to the backup

git diff backup_feature

After the work has been finished its advisable to remove the backup branch.

How do I update a branch after fulfilled merge request?

How can I delete a branch

Merge request

All updates to the main repository are made via merge requests (github refers to them as pull requests). A merge request requires the code update to be in a mergable branch in a development fork.

Merge request are also used widely to share work-in-progress with your colleagues and for code reviews. Mark such Merge request with "WIP:".

Preparation

In order to avoid conflicts, first the fork has to be updated to the main repository. The idea behind this is that all potential conflicts can be resolved by the developer with the best knowledge about the matter, while the maintainer can simple merge fast-forward.

This description expects origin pointing to the developers fork. All contributions are done to branch dev, thus it must be updated with the latest version of branch dev of main repository.

Fetch update from main repository
```
 git fetch upstream dev
```
- the update is now stored in the local index, we have fetched branch dev of the main repository
- check the log of this latest fetch
```
 git log FETCH_HEAD
```
- FETCH_HEAD is a shorthand for the head of the last branch fetched and is valid only immediately after a fetch operation
Rebase your development to the main repository, rebase means that all the new commits are done with respect to the tip of the specified branch. There can be merge conflicts which need to be resolved with appropriate changes and commits.
```
 git rebase FETCH_HEAD dev
```
- keep in mind that FETCH_HEAD is only temporarily valid, so you should do this immediately after fetch (log does not change anything)
- replace dev with appropriate branch name if other then dev is used; it is also possible to rebase a branch with other name to the remote branch, e.g.
```
 git rebase FETCH_HEAD feature-name
```
Check your commits and commit messages, eventually squash (combine) or reword. This advanced option is described later.
Push to fork. As the commit history has most likely been changed, the option -f (force) has to be used
```
 git push -f origin dev 
```

The branch dev in the fork is now ready for a merge request. The branch name can be adjusted, there is nothing preventing other branch names.

Example workflow for a Merge request

Go to your gitlab user space at [1] (replace User.Space appropriately).
Find the project fork, e.g. in the list of projects associated with you from the upper main menu.
In the line with the many columns regarding the repository, click on the "+"-symbol on the right hand side and choose "New merge request"
Select project and branch for both source and target, and click "Compare branches and continue". Remember: in almost all cases you have to merge to branch dev or other feature branch, only in very rare cases to branch master
Review the list of commits in this merge request, give it a descriptive title and description, pick an assignee
Submit the merge request