GitLab Tutorial for Beginners: Setup, SSH, Project & Workflow Guide

What is GitLab?

Overview of GitLab

GitLab is a complete DevOps platform that helps developers manage source code, collaborate with teams, and automate software delivery. It is built on top of Git, a distributed version control system, and provides additional features like CI/CD, issue tracking, and security scanning.

GitLab allows teams to manage the entire software development lifecycle from a single interface — from planning and coding to testing, deployment, and monitoring.

Key features of GitLab

Some of the most important features of GitLab include:

• Source Code Management (SCM): Host and manage Git repositories
• CI/CD Pipelines: Automate build, test, and deployment processes
• Merge Requests: Review and collaborate on code changes
• Issue Tracking: Track bugs, features, and tasks
• Security Scanning: Built-in tools for vulnerability detection
• Container Registry: Store Docker images securely
• Wiki & Documentation: Maintain project documentation

Git vs GitLab (Key Differences)

What is Git?

Git is a distributed version control system used to track changes in source code. You can start with Git basics and workflow. It allows multiple developers to work on the same project independently and merge their changes later.

With Git, developers can (see Git command cheat sheet for quick reference):

• Track file changes
• Create branches
• Merge code
• Revert to previous versions

Git works locally on your system and does not require a server.

What is GitLab?

GitLab is a web-based platform that uses Git as its core technology and adds powerful features like repository hosting, CI/CD pipelines, collaboration tools, and DevOps automation.

Unlike Git, GitLab provides:

• Remote repository hosting
• Web interface for managing code
• Team collaboration tools
• Automation pipelines

Git vs GitLab comparison table

Types of GitLab (SaaS vs Self-Hosted)

GitLab SaaS (cloud version)

GitLab SaaS is the cloud-hosted version available at gitlab.com. It is managed by GitLab and requires no installation.

Advantages:

• No setup or maintenance required
• Accessible from anywhere
• Automatic updates and backups

Best for:

• Beginners
• Small to medium teams
• Quick project setup

GitLab self-hosted (GitLab CE/EE)

Self-hosted GitLab allows you to install GitLab on your own server using GitLab Community Edition (CE) or Enterprise Edition (EE).

Advantages:

• Full control over data and infrastructure
• Custom security and compliance settings
• Suitable for enterprise environments

Best for:

• Organizations with strict security requirements
• Large teams and enterprises
• Custom DevOps workflows

When to use each option

• Use GitLab SaaS if you want a quick, hassle-free setup with minimal maintenance.
• Use self-hosted GitLab if you need full control, customization, and enhanced security.

Choosing the right option depends on your project size, security needs, and infrastructure requirements.

Pre-requisites

System requirements

Before getting started with GitLab, ensure your system meets the following requirements:

• A Linux-based system (Ubuntu, CentOS, RHEL, etc.)
• Internet connectivity
• Basic knowledge of terminal commands
• A GitLab account (we will create one in the next step)

Install Git on Linux

Git must be installed on your system to interact with GitLab repositories. Refer to create Git repository and setup basics if you are new.

For Debian/Ubuntu:

sudo apt update
sudo apt install git -y

For RHEL/CentOS:

sudo yum install git -y

Verify installation:

git --version

Step 1: Create a GitLab Account

Sign up on GitLab

1. Navigate to https://gitlab.com
2. Click on Register
3. Enter your email, username, and password
4. Follow the on-screen instructions

Verify email and login

• Check your email inbox for a verification link
• Click the link to activate your account
• Log in to GitLab using your credentials

Basic account setup

After logging in:

• Set your profile name and preferences
• Configure timezone and notifications (optional)
• Explore the dashboard

Step 2: Generate and Configure SSH Keys

Why SSH keys are required

SSH keys provide secure authentication between your system and GitLab without requiring a password every time. You can also follow a detailed guide on setting up GitLab with VS Code.

Benefits:

• Secure communication
• No need to enter credentials repeatedly
• Faster Git operations

Generate SSH key using ssh-keygen

Run the following command to generate an SSH key:

ssh-keygen -t ed25519 -C "your_email@example.com"

Press Enter to accept the default file location and optionally set a passphrase.

Add SSH key to GitLab account

Display your public key:

cat ~/.ssh/id_ed25519.pub

Copy the output and follow these steps:

1. Go to GitLab dashboard
2. Click on Profile → Preferences → SSH Keys
3. Paste the key into the text box
4. Click Add key

Test SSH connection

Verify your SSH connection with GitLab:

ssh -T git@gitlab.com

If successful, you will see a welcome message from GitLab.

Step 3: Create Your First GitLab Project

Create a new project in GitLab

1. Log in to your GitLab account
2. Click on New Project
3. Select Create blank project
4. Enter project name and description
5. Choose visibility (Public/Private)
6. Click Create project

Public vs private repositories

• Public repository: Anyone can view the code and files
• Private repository: Only authorized users can access the project

Choose based on your use case and security needs.

Initialize repository with README

While creating the project, you can choose to initialize it with a README.md file.

Benefits:

• Provides project description
• Helps users understand the purpose of the repository
• Improves documentation and usability

After creation, your repository is ready for development and collaboration.

Step 4: Clone GitLab Repository to Local System

Clone using SSH

After creating your project, you need to clone it to your local system.

1. Go to your GitLab project
2. Click on Clone
3. Select Clone with SSH and copy the URL

Run the following command in your terminal (see more in git clone examples):

git clone git@gitlab.com:username/project-name.git

Replace username and project-name with your actual details.

Verify cloned repository

Navigate into the cloned directory:

cd project-name

List the files to confirm:

ls -l

If the repository contains a README or other files, they will appear here.

Step 5: GitLab Workflow Explained

What is staging in Git?

Staging is the process of preparing changes before committing them. It allows you to selectively include files in the next commit. Learn more in git add and staging concepts.

Example:

git add file.txt

What is commit?

A commit is a snapshot of your changes saved in the Git repository. See git commit message best practices.

Example:

git commit -m "Add new file"

What is branching?

Branching allows you to create separate lines of development without affecting the main codebase. Refer to git branch examples

Example:

git switch -c feature-branch

What is merge request?

A merge request (MR) is a request to merge changes from one branch into another (usually into main). It allows code review and collaboration.

What is merging?

Merging combines changes from one branch into another. See git merge examples.

Example:

git merge feature-branch

Step 6: Manage GitLab Project Using CLI

In this section, we will manage a GitLab project using the command line interface (CLI). This is the most common and efficient way developers interact with GitLab repositories in real-world scenarios.

You will learn how to create branches, add files, stage changes, commit updates, merge code, and push changes to the remote GitLab repository. These are the core Git operations that form the foundation of any GitLab workflow.

Create and switch branch

Create a new branch and switch to it (see git switch command). This helps you work on features or changes without affecting the main branch.

git switch -c new-branch

Create files in repository

Create a new file inside your repository.

touch file.txt

Stage changes

Add the file to the staging area so it can be included in the next commit (learn more in git add and unstage files):

git add file.txt

Commit changes

Save your changes with a meaningful commit message (see git commit amend examples):

git commit -m "Add file.txt"

Merge branch to main

Switch to the main branch and merge your changes (compare merge vs rebase):

git checkout main
git merge new-branch

Push changes to GitLab

Upload your changes to the remote GitLab repository (see git push examples):

git push origin main

Step 7: Manage GitLab Project Using GitLab GUI

Create branch using GUI

1. Open your project in GitLab
2. Click on the branch dropdown
3. Select New branch
4. Enter branch name and click Create branch

Create and edit files

1. Click on Repository → Files
2. Click New file
3. Add file name and content

Commit changes using GUI

Scroll down and:

• Add a commit message
• Select target branch
• Click Commit changes

Create merge request

1. Go to Merge Requests
2. Click New merge request
3. Select source and target branches
4. Click Create merge request

Merge changes in GitLab

1. Review the merge request
2. Click Merge
3. Confirm the merge

Your changes will now be merged into the target branch.

Summary

In this guide, you learned how to get started with GitLab step by step. We covered:

• Understanding what GitLab is and how it differs from Git
• Creating a GitLab account and configuring SSH keys
• Creating your first GitLab project
• Cloning repositories to your local system
• Understanding GitLab workflow (staging, commit, branching, merging)
• Managing projects using both CLI and GitLab GUI

GitLab is a powerful platform that combines version control with DevOps capabilities, making it easier to collaborate, automate workflows, and manage projects efficiently.

With regular practice, you can move beyond basics and explore advanced topics like git rebase, git stash usage, and git reflog recovery.

Official Documentation

• GitLab Official Documentation
• GitLab Basics Guide
• SSH Key Setup in GitLab
• Managing GitLab Projects