GitLab for Beginners: A Step-by-Step Tutorial

Learn version control, collaboration, and CI/CD basics in under an hour.

If you’ve heard developers talk about “pushing to GitLab” or “opening a merge request” and felt lost, this guide is for you. By the end, you’ll have created an account, set up your first project, pushed code, collaborated through merge requests, and run your first automated pipeline.

What Is GitLab?

GitLab is a web-based platform built around Git, the version control system that tracks changes to your code. On top of hosting your repositories, GitLab provides:

• Issue tracking to plan and organize work
• Merge requests for code review and collaboration
• CI/CD pipelines to automatically test and deploy your code
• Built-in security scanning, wikis, and package registries

Think of it as one workspace where your code, your team’s conversations, and your deployment automation all live together. You can use GitLab.com (the hosted version) or install GitLab on your own servers.

GitLab vs. GitHub: A Quick Note

Both platforms are built on Git, and the basic workflow is nearly identical. GitLab’s main differentiators are its all-in-one DevOps approach (CI/CD is built in, not an add-on) and the option to self-host. If you learn one, picking up the other takes very little effort.

Step 1: Create Your GitLab Account

1. Go to gitlab.com and click Register.
2. Sign up with your email, or use Google or GitHub to log in.
3. Verify your email address and complete the short onboarding questions.

That’s it. You now have a free account with unlimited private repositories.

Step 2: Install Git on Your Computer

GitLab hosts your code, but you work on it locally using Git. Check whether you already have it:

git --version

If not, install it:

• Windows: Download Git from git-scm.com
• macOS: Run brew install git or install Xcode Command Line Tools
• Linux (Debian/Ubuntu): Run sudo apt install git

Then tell Git who you are:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Step 3: Set Up SSH Authentication

SSH keys let you push and pull code without typing your password every time.

1. Generate a key:

ssh-keygen -t ed25519 -C "[email protected]"

2. Press Enter to accept the default location, and optionally set a passphrase.
3. Copy your public key:

cat ~/.ssh/id_ed25519.pub

4. In GitLab, click your avatar, choose Preferences, then SSH Keys. Paste the key and click Add key.
5. Test the connection:

ssh -T [email protected]

You should see a welcome message with your username.

Step 4: Create Your First Project

In GitLab, a project holds a repository plus everything around it (issues, pipelines, wiki, and more).

1. Click the + icon in the top bar and select New project/repository.
2. Choose Create blank project.
3. Enter a project name, such as my-first-project.
4. Set visibility to Private for now.
5. Check Initialize repository with a README and click Create project.

Step 5: Clone the Repository

Cloning copies the project from GitLab to your computer. On your project page, click Code, copy the SSH URL, and run:

git clone [email protected]:your-username/my-first-project.git
cd my-first-project

Step 6: The Core Git Workflow

This is the loop you’ll repeat constantly: edit, stage, commit, push.

Create a new file:

echo "Hello, GitLab!" > hello.txt

Check what changed:

git status

Stage the file (prepare it for saving):

git add hello.txt

Commit it (save a snapshot with a message):

git commit -m "Add hello.txt"

Push it to GitLab:

git push origin main

Refresh your project page and you’ll see hello.txt there. Congratulations, you’ve just published your first commit.

Tip: Write commit messages in the imperative mood and keep them descriptive, like “Fix login bug” instead of “stuff.” Your future self and teammates will thank you.

Step 7: Work with Branches

Branches let you work on changes in isolation without touching the main codebase.

git checkout -b feature/update-readme

Edit your README, then commit and push the branch:

git add README.md
git commit -m "Improve README description"
git push -u origin feature/update-readme

GitLab will print a link in your terminal for creating a merge request, which leads us to the next step.

Step 8: Open a Merge Request

A merge request (MR) is a proposal to merge your branch into another, usually main. It’s where code review happens.

1. In GitLab, go to Code > Merge requests and click New merge request.
2. Select your source branch (feature/update-readme) and target branch (main).
3. Write a clear title and description explaining what changed and why.
4. Optionally assign a reviewer, then click Create merge request.

Teammates can leave comments on specific lines, suggest changes, and approve the MR. Once approved, click Merge. Your changes are now part of main.

Afterward, update your local copy:

git checkout main
git pull origin main

Step 9: Track Work with Issues

Issues are GitLab’s way of tracking tasks, bugs, and ideas.

• Go to Plan > Issues and click New issue.
• Add a title, description, labels, assignee, and due date.
• Reference an issue in a commit or MR with its number (for example, #1).
• Write Closes #1 in an MR description and the issue closes automatically when the MR merges.

For visual planning, try Issue Boards, a Kanban-style view where you drag issues between columns like To Do, Doing, and Done.

Step 10: Your First CI/CD Pipeline

CI/CD (Continuous Integration and Continuous Delivery) automatically builds, tests, and deploys your code whenever you push. It’s GitLab’s signature feature, and it’s easier to start than you might think.

In the root of your project, create a file named .gitlab-ci.yml:

stages:
  - build
  - test

build-job:
  stage: build
  script:
    - echo "Building the project..."

test-job:
  stage: test
  script:
    - echo "Running tests..."

Commit and push the file. Then open Build > Pipelines in GitLab. You’ll see your pipeline running, with each job passing through its stage. Click any job to view its log output.

A few concepts worth knowing:

• Stages run in order; jobs within a stage run in parallel.
• Jobs are the individual tasks defined in your YAML file.
• Runners are the machines that execute jobs. GitLab.com provides shared runners, so you don’t need to set anything up.

Once you’re comfortable, replace the echo commands with real ones, such as npm test or pytest.

Beginner Best Practices

• Commit small and often. Small commits are easier to review and undo.
• Never commit secrets. Passwords and API keys belong in GitLab’s CI/CD variables, not your code.
• Protect your main branch. In Settings > Repository > Protected branches, require merge requests before changes reach main.
• Use a .gitignore file to keep build artifacts and dependencies out of your repo.
• Write a good README so others know how to use and contribute to your project.

Common Beginner Mistakes

• Forgetting to pull before pushing. Run git pull first to avoid conflicts.
• Working directly on main. Use branches for every change.
• Vague commit messages. Be specific about what changed.
• Ignoring pipeline failures. A red pipeline is useful feedback, so read the job log.

Quick Command Cheat Sheet

Command	What it does
git clone <url>	Copy a repo to your machine
git status	Show changed files
git add <file>	Stage changes
git commit -m "msg"	Save a snapshot
git push	Upload commits to GitLab
git pull	Download the latest changes
git checkout -b <name>	Create and switch to a new branch
git log --oneline	View commit history

Where to Go Next

You now know the essentials: accounts, SSH, repositories, branches, merge requests, issues, and CI/CD. From here, explore:

• GitLab Pages to host a free static website
• Container Registry to store Docker images
• Security scanning to catch vulnerabilities automatically
• The official GitLab documentation at docs.gitlab.com, which is excellent

The best way to learn is to build something. Create a small project, break it, fix it, and ship it through a pipeline. Happy committing!