Creating and administrating a forked repository

Warning

Only team leaders should create forks for their repositories. Each team should create one fork.

1. Creation of a new fork repository

A. Accessing the upstream repository

As presented in the GIT&GitLab Workflow Documentation file, to work in the project a fork needs to be created from the upstream repository.

In the main GitLab page, navigate on the bottom of the page to the Public projects (Figure 23) section (Browse projects), then click All and all the public repositories will be shown (Figure 24):

Figure 23 Initial main window

Figure 24 Public projects

For the following scenario, the repository that will be used is named STEPlib-DEMO.

It must be noted that this repository is stored in the creator’s folder. In this case, the Master user is Jonathan Bernales and the project is named STEPlib-DEMO.

To access the repository, simply click on it and the following interface will be shown:

Figure 25 Main GitLab UPSTREAM project interface

B. Forking the repository

To fork the project, simply click on the fork button next to the project URL as seen in Figure 25.

GitLab will then ask you to which users the project shall be forked. Simply select your user and the server will automatically fork the repository:

Figure 26 Forking the project for a team leader

Once the project is forked, a confirmation ribbon will appear and you will be redirected to your forked repository:

Figure 27 Forked repository interface

A couple of points need to be detailed:

• As it can be seen in the top-left corner of this figure, the repository is now located in the user who forked the upstream.
• The user who forked the upstream repository is now master of their fork, meaning they can completely manage and customize the fork.
• GitLab still knows from which project this repository has been forked from.

If this process has gone smoothly, when logging in to GitLab and navigating to Your projects the new forked repository should appear:

Figure 28 Project result after forking

• Jean Brange / STEPlib-DEMO is the forked repository
• Jonathan Bernales / STEPlib-DEMO is the upstream repository

2. Managing the forked repository

A. Managing user privileges and project name

Since you now have the Master access rights in the forked repository, different options become available. Since the fork is a copy of the upstream repository, all the project attributes are also copied except for user rights. The only user that will have access to the forked repository will be the one that will have made the fork procedure.

These options are available in the top-right menu in the project window:

Figure 29 Project options menu

In this scenario we will cange the forked repository name to a more clear name. In this case “FORK-AP242”. To do so, click on Settings->General in the project menu (Figure 29). The changes should be done in the Project name and the Path fields in the Rename repository section scrolling down.

The following window will appear:

Figure 30 Project settings

Different attributes can be changed such as the project visibility. If this value is set to “Internal” then every logged in user will be able to see and clone the project. If you scroll down you will find the “Rename repository” section and you will be able to rename the path.

To allow users to have access to the forked repository, access the project menu (Figure 29) and select Members. The following window will appear:

Figure 31 Project “members” menu

In the first field, simply write the user to which you wish to grant access. Role permissions details can be found here.

B. Creating the team custom project branch

By default, the upstream repository will have 3 branches that will be “master”, “dev” and “release”. As described in the workflow description document, these branches will be infinite and will never be closed. For each new developed feature (Change Request or project), a new branch should be created in the forked repository so each developer can work freely without polluting the “dev” branch.

To create a new branch, navigate to the Repository tab and select Branches (Figure 25). Clicking on the New Branch button will show a window in which the new branch name should be indicated:

Figure 32 GitLab project Branches menu

The new project branch should be created from the dev branch and have a clear name:

Figure 33 Branch creation

3 Cloning the forked repository

A. Cloning the forked repository and it’s branches

Through this section, we will present the process of cloning the forked repository locally allowing us to start working with the development. The EGit Eclipse plugin will be used to illustrate the following scenario. Multiple GIT GUI clients exist, the most popular being GIT Kraken with professional support for Mac, Windows and Linux. This GIT client was presented in the previous document, and is highly recommended since it adds a GitLab integration to manage different elements.

If your workspace doesn’t display the egit interface, click on right button then click “Show in” and choose “Git Repositories” as seen in Figure 34:

Figure 34 EGit display menu

The EGit menu can be usually found at the bottom left of the Eclipse window:

Figure 35 EGit Interface

To download the repository, simply select “Clone a Git repository”. The following menu will appear asking for an URI. This URI can be found in the GitLab main project interface preceded by the SSH tag (Figure 25). Be sure that the cloned repository is the fork:

Figure 36 EGit clone menu

Warning

In the figure 24, the path was changed to match the project name, in this case: FORK-AP242

EGit will complete the Host, Repository path, User and Passwords fields. The result should be the same than Figure 34. You must however precise the communication protocol: SSH.

A message indicating that the host authenticity can’t be established will appear. You should indicate that you trust the connection:

Figure 37 Host authenticity warning

Note

If a passphrase was added when the SSH key was created, a new popup will appear asking you to indicate that value. This is not the git2.boost-lab.net password but the password of the SSH Key you have created in the section 2.2 C

Figure 38 SSH Key passphrase popup

The next window will ask you to indicate which branches will need to be cloned. We can see that the branch created on GitLab (in this case AP242) is also available for cloning.

Since you are a team leader, it is interesting for you to clone all the branches.

Figure 39 caption

Warning

Once again, we can see that the repository URL remains the same even if the fork repository name changed. The AP242 branch is the branch created in the section 3.2 B

Finally, you will have to select a local directory to where the fork will be cloned. The initial branch that must be selected is the dev branch. By default, the repository in the server will be named “origin”. This is a GIT convention and is applied by default by every GIT client:

Figure 40 Local directory and initial branch definition

Once the project has been cloned, the EGit interface should look like this:

Figure 41 Imported repository view from EGit

As you can see, different kind of branches are created when cloning a repository: the local branches are the physically present branches. In this case, only the dev branch exists.

B. Creation of local branches

Since our local repository only has the dev branch, we need to create the AP242 branch (for example) to synchronize the changes from the forked repository locally.

To create a new branch, simply right-click on the Local section and navigate: Switch To New Branch...

Figure 42 New branch menu

To make the process easier and faster, the branch name should be the same as the origin branch name. In this case the AP242 name will be used. In the Figure 41, we indicate to EGit that the newly created branch will be in sync with the origin/AP242 branch. To do so in the Source section click on Select... and select the origin/AP242 branch:

Figure 43 Branch sync local/fork

To download changes from origin (the forked repository), right-click on the repository icon and select Pull...

Figure 44 Pull... option

The following window will ask from which branch the pull should be done:

Figure 45 Pull menu

Note

The selected reference will be pulled in the actual branch. Be sure that you are in the correct branch. If not, simply double-click on the branch you want to download information.

4. Working with the upstream repository

A. Cloning the upstream repository branches

Since you are the team leader who has forked the repository, it is your responsibility to keep in sync the forked repository with upstream repository. It will also be your responsibility to create merge requests whenever your project branch is mature enough to be shared in the upstream’s dev branch.

To add the upstream repository, right-click the Remotes tab and select Create Remote...:

Figure 46 Remotes menu

The window that will appear will ask you to give a name to the new remote. In this case, and as a GIT good practice process, we will name the remote “upstream”. Be sure to configure the fetch option since we will not push directly to the upstream repository:

Figure 47 Remote creation menu

The next step will ask you for an URI. Click on Change... and the window like in Figure 30 will appear... Please be sure that the selected URI is the upstream’s URI. This URI can be accessed in the main gitlab page (Figure 27) by selecting the upstream repository and copying it’s SSH URL:

Figure 48 Additional remote URI definition

If the process has been successful, you should now see the upstream branches in the “Remote tracking” branches section:

Figure 49 Remote tracking section after adding the upstream repository

B. Creating a merge request in GitLab

Note

This scenario is only applicable if changes have been done in the forked repository. Please check the developper section (nº4) if you want to modify some files to merge them.

If the resulting work from the AP242 is mature enough to be merged back into the upstream deb branch, a new merge request will have to be created. To do so, navigate to your GitLab’s fork window and select the Merge Requests tab:

Figure 50 Main GitLab’s fork menu

Simply click on the New Merge Request button:

Figure 51 Creation of a new merge request

The merge request should be done to integrate the latest changes from a project branch (in this case the AP242) into the “dev” branch from the upstream repository. This can be seen in the following figure, where the AP242 branch from the forked repository will be merged with the dev branch from the upstream repository:

Figure 52 Merge request repository and branch selection

After clicking on “Compare branches and continue” we will land on a Merge Request description page. In this page, information related to the merge request will be added.

A Description of the changes should be added and detail as much as possible which specific changes have been made. At the bottom of this page, the different commits that are being merged and the modified files are added to have a quick view of the changes.

The following figure shows the Merge Request description page:

Figure 53 Merge request description

C. Pulling from the upstream repository into a local branch

To be able to check if the upstream repository has been updated, right-click on the repository icon and select Remote -> Fetch…:

Figure 54 Fetch button

Since we want to check if updates have been made in the upstrem repository, select “upstream” in the next window:

Figure 55 Repository selection for fetch

If changes have been made in the upstream repository, we want to download them locally. Therefore we want to pull from the upstream repository. To do so checkout to the local dev branch by double clicking on the branch. Then right click on the repository icon and in the menu select Pull...

Figure 56 Pull... menu

Then select the upstream repository for the Remote field and the dev branch. This way EGit will download the upstream dev changes to our local dev branch.

Figure 57 Pull remote selection

Our local dev branch will now contain the latest upstream changes. However the forked repository doesn’t have yet those changes.

D. Pushing from the local branch to the fork repository

We now want to push back our local changes to the fork repository. To do so right click on the local dev branch and select Push Branch...

Figure 58 Push branch menu

The next window will ask us to where the changes shall be pushed. In this case we want to upload those changes in the forked repository. Therefore, we are going to select as a Remote “origin” and the branch to which we are pushing the changes is the “dev” branch:

Figure 59 Pushing the upstream local changes to fork