Skip to content

First Steps with Git and GitLab

Purpose

This guide is for new team members of NFDI4Immuno who are completely new to GitLab and Git. It focuses on the GitLab web interface and basic local Git setup on Windows, including how to create an SSH key, connect it to GitLab, set up Git locally, and work with a repository.

The NFDI4Immuno projects are hosted at https://codebase.helmholtz.cloud/nfdi4immuno. The metadata-schema project is used as an example throughout this guide - the steps are the same for any other NFDI4Immuno project, just replace the project name and URLs with those of the project you work on.

Once you are comfortable with the basics, continue with the GitLab Workflow Developer Role, which describes the full workflow used in the NFDI4Immuno projects.

Quick Reference Workflow

  1. Set up Git and SSH access on your Windows computer
  2. Clone the repository locally
  3. Create an Issue (to describe your task or bug)
  4. Create a Merge Request (MR) from that issue (this creates a branch and a draft MR)
  5. Make local changes (edit, commit, push)
  6. Make the MR ready to submit your work for review

Full Workflow

Steps 1 to 5 set up your computer and are only needed once. Steps 6 to 9 are repeated for every task you work on.

Step 1: Install Git on Windows

What: Install Git and the Git Bash terminal on your computer.

How:

  1. Download Git for Windows: https://git-scm.com/downloads
  2. Run the installer and follow the default options (you can leave most settings unchanged)
  3. After installation, open Git Bash (installed automatically with Git)
  4. Check that Git is installed correctly:
git --version

If it prints something like git version 2.x.x, you're good to go.

Step 2: Create an SSH Key

What: Generate a pair of SSH keys on your Windows computer.

Why: SSH keys allow you to connect securely to GitLab without typing your password each time.

How:

  1. Open Git Bash
  2. Run the following command (replace with your own email):
ssh-keygen -t ed25519 -C "your.email@institution.org"
  1. When asked for a file location, press Enter to accept the default (/c/Users/<your name>/.ssh/id_ed25519)
  2. When asked for a passphrase, you can either set one or leave it empty

You should now have two files in C:\Users\<your name>\.ssh:

  • id_ed25519: your private key
  • id_ed25519.pub: your public key

Avoid:

  • Sharing your private key - keep this secret!

Step 3: Add the SSH Key to GitLab

What: Register your public key with your GitLab account.

How:

  1. Open a project page in GitLab, e.g. metadata-schema
  2. In the top-right corner, click your profile picture > Preferences
  3. In the left menu, select SSH Keys
  4. Open the public key file (id_ed25519.pub) using Notepad:
notepad ~/.ssh/id_ed25519.pub
  1. Copy the entire contents of the file
  2. In GitLab, click Add new key to open the form. If the Key field is already shown, skip this step
  3. Paste the copied contents into the Key field
  4. Add a short Title (e.g., "My Windows laptop")
  5. Click Add key

Your computer is now authorized to connect to GitLab via SSH.

Step 4: Configure Git

What: Tell Git your name and email address. You only need to do this once on your machine.

How:

  1. Set your name and email:
git config --global user.name "Your Name"
git config --global user.email "your.email@institution.org"
  1. Verify your settings:
git config --list

Step 5: Clone the Repository

What: Download the code to your local machine.

How:

  1. Go to the project page, e.g. https://codebase.helmholtz.cloud/nfdi4immuno/portal-infra/metadata-schema
  2. Click the blue Code button (top-right corner)
  3. Select the SSH option and copy the URL. For metadata-schema it looks like:
git@codebase.helmholtz.cloud:nfdi4immuno/portal-infra/metadata-schema.git
  1. In Git Bash, navigate to a folder where you want to keep your projects, e.g.:
cd ~/Documents
  1. Clone the repository using the URL you copied, e.g.:
git clone git@codebase.helmholtz.cloud:nfdi4immuno/portal-infra/metadata-schema.git

You now have the project locally on your computer, in this example in the folder metadata-schema.

Step 6: Create an Issue

What: An issue describes what needs to be done.

How:

  1. Go to Issues in the project, e.g. metadata-schema Issues
  2. Click New issue
  3. Fill in:
  4. Title: Short and clear (e.g., Add new metadata field for antibodies)
  5. Description: Briefly describe the goal
  6. Labels: Select relevant ones if available
  7. Assignee: Leave empty or assign to yourself (only one assignee per issue in free tier GitLab)
  8. Click Create issue

You've now created a task to work on.

Step 7: Create a Merge Request from the Issue

What: Create a branch and a draft merge request directly from the issue. Each issue should have its own branch. The name of the branch must start with the issue number, followed by a dash.

Why: Creating the merge request from the issue links your work to the issue and gives the branch the correct name automatically. The 'Draft' status signals that the work is still in progress.

How:

  1. Open the issue you just created
  2. Click the Create merge request button near the top right
  3. This automatically creates:
  4. A new branch named {issue-number}-{issue-title} (e.g., 42-add-new-metadata-field-for-antibodies)
  5. A draft merge request linked to the issue
  6. In the merge request creation page, verify:
  7. Target branch is set to development (NOT main) - this is also the branch your new branch is created from
  8. The merge request is marked as Draft
  9. Click Create merge request at the bottom

A new branch and a draft merge request are now available for you.

Tips:

Step 8: Make Local Changes

What: Get your branch, make changes, commit them, and push them to GitLab.

How:

  1. In Git Bash, move into your project folder, e.g.:
cd metadata-schema
  1. Check out your new branch:
git fetch origin
git checkout <your-branch-name>
  1. Make your code or document changes (e.g., update files)
  2. Stage and commit your changes:
git add .
git commit -m "feat: add new metadata field for antibodies"
  1. Push your work to GitLab:
git push

Your changes are now uploaded to GitLab and visible in the merge request.

Tips:

Step 9: Make the Merge Request Ready for Review

What: Describe your changes and submit the merge request for review.

Why: The draft merge request was created before any work was done. A clear description and removing the 'Draft' status tell the reviewer what changed and that your work is ready to be looked at.

How:

  1. Go to Merge requests and open the merge request you created in Step 7
  2. Click Edit and check the form:
  3. Title: GitLab usually fills this automatically

  4. Description: Describe what you did, and reference the issue (GitLab adds the Closes line automatically when the merge request is created from the issue):

    Added a new metadata field for antibody type.
Closes #123

  5. Target branch: Usually development

  6. Reviewer: Assign your mentor or reviewer
  7. Click Save changes
  8. At the top of the merge request, click Mark as ready - the "Draft:" prefix is removed from the title

Your code is now ready for review.

Tips:

What Happens Next

  • Your reviewer will check your MR and leave feedback

  • If you need to make fixes:

    1. Edit locally

    2. Stage, commit, and push:

      git add .
git commit -m "fix: address review comments"
git push

    3. The MR updates automatically

    4. Once approved, a maintainer will merge it

Additional Resources