Skip to content

Working with remote repositories in GitLab

Overview

Now, we want to publish our local repository on GitLab and learn how to exchange commits between different repositories.

Tips for instructors
  • Please make sure that everybody follows along closely since these are critical steps to be able to follow the rest of the workshop. It may take some time to fix all issues (see list below for typical pitfalls). Use the following break to resolve complicated cases. Two instructors are highly recommended for this section.
  • Personal access tokens are used in this episode for authentication instead of SSH (which is in general the preferred way), since the setup can become quite complicated.

Checkpoints:

  • Please make sure that all participants created a personal access token and understood to keep it for the following step.
  • Please make sure that all participants created an empty repository without a README file. Otherwise, they are not able to push their repository.
  • Please make sure that all participants see their content in the repository after a successful push.

So far, we have only worked locally. Usually, however, you work with several Git repositories between which you synchronize. Repositories that are not located on your computer are called remote repositories. Git is quite flexible and supports different ways to work with multiple Git repositories. We are about to introduce a central remote Git repository which is managed by GitLab (see also: “Subversion-Style Workflow”).

Publish the local Git repository in GitLab

In the following, we want to set up the central remote Git repository in GitLab on the basis of our local Git repository.

Set up a personal access token

First, you need to create an access token which you can use later for authentication in GitLab via your Git client:

  • Navigate to the Access tokens section of your GitLab profile: https://codebase.helmholtz.cloud/-/user_settings/personal_access_tokens.
  • Click the Add new token button to create a new access token:
    • Set the Token name to git-access.
    • Leave the description empty and the expiration date as it is defined. After the expiration date has been reached, you can no longer use the access token and you need to define a new one. The usage of access tokens with limited lifetime is a security good practice.
    • Select the scopes read_repository and write_repository. Scopes define what you can do with the access token. In this case, the generated access token allows you read and write access to your Git repository.
    • Create your access token by clicking the Create token button.

Hints regarding personal access token

  • Please note that you cannot retrieve the access token after you closed the web page.
  • In case you lose your token you can remove it and add new access token at any time.

Create a new GitLab project

In the next step, we create a new GitLab project which contains the central remote Git repository:

  • Navigate to the workshop GitLab group.
  • Click the New project button and afterwards the Create blank project button to get to the GitLab project creation dialog:
    • Set the Project name to planets-<Your Last Name>.
    • Please make sure to deselect Initialize repository with a README. Otherwise you cannot properly publish your local Git repository in GitLab.
    • Click the Create project button to create your GitLab project. Afterwards GitLab redirects you to the overview page of your GitLab project.

Further hints regarding project creation

  • The Project URL allows you to select different namespaces (groups, subgroups, your user namespace). We create a project in a specific group namespace. Later, you could also move your project to another namespace.
  • You can define different visibility levels:
    • private: Only explicitly added project members can see and do something with the GitLab project.
    • internal: Only authenticated users of the GitLab instance can access the GitLab project.
    • public: The GitLab project is visible even for unauthenticated users.
    • Please note that depending on the GitLab instance configuration, not all visibility levels might be available.
  • On the GitLab project page:
    • The Git repository managed by GitLab is currently empty and does not contain any commits. For that reason, GitLab provides information about how you can add content to it. We are in the scenario comparable to the described Push an existing Git repository case.
    • We will use the HTTPS protocol for transferring our local Git repository to GitLab. For that reason, please copy the HTTPS URL of the remote Git repository by clicking the Code drop-down menu and the Clone with HTTPS copy button.

Push the local Git repository to your GitLab project

Now, we want to publish our local Git repository in GitLab and make it the central remote Git repository:

  • Switch back to your Git shell.
  • git status - Please make sure that there are no uncommitted changes and that you are on branch main.
  • git remote - Shows the defined remote repositories. The list is currently empty.
  • git remote add origin <copied URL> - Creates a link to the remote Git repository on the GitLab instance. The URL should look similar to: https://codebase.helmholtz.cloud/<YYYY-MM-DD-introduction-to-git-and-gitlab>/planets-<username>.git. origin is the default name for the remote repository if you follow a “Subversion-Style Workflow”.
  • git remote -v - Shows two entries for origin. One which defines where we “push” changes to and another one which defines from which we “fetch” changes. These URLs are the same when you follow the “Subversion-Style Workflow”. From now on, we can refer to our remote Git repository using the name origin.

So far, we have only created the link to communicate with our remote repository. In the next step, we finally want to publish the commits of our local repository in GitLab. For this purpose, Git requires network access and you have to authenticate yourself in GitLab using the created access token.

  • git push - Pushes the commits of our current branch to the remote Git repository. However, the command shows an error message because we have not explicitly specified to which remote branch we want to push. Luckily, Git tells us what to do and we use the proposed command.
  • git push --set-upstream origin main - Instructs Git to push the (missing) commits of our current branch to the main branch of the remote repository.
    • Git connects to the remote Git repository and tries to authenticate. For that purpose, Git requests to enter your username and password via the command line or via a separate dialog. Please enter token as username and your personal access token as password.
    • If everything works properly, the Git output indicates the transfer of the commits. Otherwise it might show an error message. Please see the “Typical pitfalls” information box for typical problems and their solutions.

Typical pitfalls

  • Authentication error when accessing the repository:
    • Problem: Git shows an error message similar to: remote: HTTP Basic: Access denied. If a password was provided for Git authentication, the password was incorrect or you're required to use a token instead of a password. If a token was provided, it was either incorrect, expired, or improperly scoped. See ... fatal: Authentication failed for 'https://codebase.helmholtz.cloud/...'
    • Possible reason: You might have entered the wrong access token or the username was empty.
    • How to resolve: Run the push command again and make sure that you enter the correct authentication information.
  • Authentication error without asking for authentication information:
    • Problem: Git shows an error message similar to the error message above but you were not asked for any authentication information.
    • Possible reason: You might have already accessed the GitLab instance but the cached token is no longer valid.
    • How to resolve: Run the push command again. This time, Git should ask for your authentication information again.
  • Permission denied when accessing the remote repository:
    • Problem: Git shows an error message similar to: Permission denied (publickey). fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
    • Possible reason: An invisible character was added at the front of the Git repository URL. This can happen if you use Ctrl+V to copy the URL instead of the copy button in the GitLab Web UI.
    • How to resolve: Copy the URL using the copy button and set the new URL for origin using the command: git remote set-url origin <new URL>.
  • The shell seems to halt after the push command:
    • Problem: Git still runs but it does not print any output.
    • Possible reason: The authentication dialog is opened in the background and Git waits for your input.
    • How to resolve: Check the task bar for a new element. It uses the default task icon.
  • Git repeatedly asks for your authentication information:
    • Problem: You have to enter your authentication information for every interaction with the remote Git repository.
    • Possible reason: There is no credential manager set up to cache your authentication information.
    • How to resolve: Set up a credential manager.

If everything worked for you, please reload your GitLab project page in your Web browser. Now you can see the files and their history on GitLab. Congratulations!

On the Gitlab project page, you can use different Git features which we already used on the shell:

  • You can click the History button in the GitLab repository view (Code => Repository) to see the version history (similar to the command git log --oneline).
  • You can see the repository graph via Code => Repository graph (similar to our defined alias command git graph).
  • You can change files in the repository via the Web IDE (Code => Open with ... Web IDE) or via a single file editor (select a file, click Edit => Edit single file).

Synchronize the local Git repository with changed content

Now, we want to change the remote Git repository via the GitLab Web interface and see how we can update our local Git repository.

Change the mars.txt via the GitLab Web interface

First, we want to change the mars.txt in the remote Git repository:

  • Navigate to the overview page of your GitLab project.
  • Select the file mars.txt.
  • Click the Edit drop-down menu (top right corner) and select Edit single file:
    • Add another fact about Mars at the end of the file: 
      We have to bring our own oxygen
    • Click the Commit changes button (top right corner).
    • Write a good commit message in the opened commit dialog: Add notes about the Mars atmosphere.
    • Perform the commit to the current main branch by clicking the Commit changes button.
  • You can check via Code => Commits that the history of the remote repository contains your new commit.

Synchronize your local Git repository

Next, we want to synchronize the local with the remote Git repository:

  • Switch back to your Git shell.
  • git graph - Only shows our local commits but not the changes we did in GitLab. The new commit only exists in the remote Git repository on GitLab.
  • git fetch origin main - Checks if there is anything new in the remote Git repository on branch main. The output shows that a new commit was fetched.
  • git graph - Now, we can see a new commit in the graph. But our local main branch still points to the latest local commit.
  • git status - Tells us that we are one commit behind the main branch of the remote repository (origin/main). In addition, the output tells us that we can use git pull to retrieve the changes.
  • git pull - Retrieves the commit and applies it to our local main branch.
  • git status - Indicates that our local Git repository is in sync with the remote repository.
  • git graph - Both main branches (local and remote) point to the latest commit.

Fetch and pull

  • You normally run git pull directly. In this case, Git fetches the commits and applies them directly to your local branch.
  • git fetch allows you to view the changes first and then to decide whether you want them to directly apply or not. For example, you could check them via git diff main origin/main.
  • If you use git pull, it implicitly performs a git merge as well. The git status hint that it can be fast-forwarded tells us it will not create a merge commit and keeps our version history linear.

Key points

  • A GitLab project is a way to share your Git repository with others.
  • Personal access tokens are one option to authenticate from your local Git shell with GitLab via HTTPS. Personal access tokens cannot be retrieved after creation.
  • To interact between the local Git repository and the Git repository on GitLab, we used two commands:
    • git push is used to publish commits from your local Git repository to the remote Git repository on GitLab.
    • git pull is used to retrieve commits from the remote Git repository on GitLab to your local Git repository.