How to Use GitLab: The Beginner's Guide (First Project, First Merge Request, and Your First Pipeline)

CodexFuse Team · 2026-10-30T14:18:33.623Z · 11 min read

How to Use GitLab: The Beginner's Guide (First Project, First Merge Request, and Your First Pipeline)

Learning how to use GitLab is simpler than it looks from the outside: you create a free account, make your first project, connect it to your computer with an access token, push your first commit, open a merge request, and run your first CI/CD pipeline — usually in one sitting. GitLab is a web-based DevOps platform that combines Git repository hosting with built-in CI/CD, code review, issue tracking, and project management in one place, so beginners get the full workflow without bolting on extra services. This guide walks that whole arc in the current GitLab interface (checked against the official docs, v19.6, October 2026), because the most-linked beginner guides still show older menus and the navigation has moved since.

How do you use GitLab? The complete beginner workflow

Here is the whole journey in eight steps. Each section below expands one step with exact click paths and commands.

1. Create your GitLab account at gitlab.com and verify your email.
2. Create your first project with Create new (+) > New project/repository > Create blank project.
3. Generate a personal access token under avatar > Edit profile > Access > Personal access tokens — you will use it as your password for Git.
4. Clone the project to your computer and configure your Git identity.
5. Commit and push your first change with git add, git commit, and git push.
6. Open a merge request from a feature branch and click Merge.
7. Add a .gitlab-ci.yml file and watch your first pipeline run at Build > Pipelines.
8. Invite a teammate at Manage > Members > Invite members — and know the self-hosted option exists when you outgrow the cloud.

How do I create a GitLab account?

You create a GitLab account in about two minutes at gitlab.com: click Sign up, enter your name, username, email, and a strong password, then click through the email verification link GitLab sends you. Since this password guards your code, make it genuinely strong — a free password generator builds one you could never guess, and GitLab's own welcome questionnaire then asks your role and why you are signing up so it can tailor the dashboard. That is the whole setup: no credit card, no install, no server to configure before you can start.

What is GitLab, and how is it different from GitHub?

GitLab and GitHub both host Git repositories and offer the same core rhythm — clone, commit, push, review, merge — but GitLab bundles the surrounding DevOps tools (CI/CD pipelines, container registry, issue boards) into the same product while GitHub leans on separate services and marketplace actions. For a beginner the practical difference is small: both use Git underneath, both have merge/pull requests, and skills transfer directly, as the GitHub beginner guide shows for the other platform. Choose GitLab when you want built-in CI/CD and the option to self-host the exact same software later; the rest of this guide assumes that choice.

How do I create my first GitLab project?

A GitLab project is the container for one repository plus its issues, merge requests, and pipelines — and creating your first project takes about thirty seconds. Click the Create new (+) button in the upper-right corner, choose New project/repository, then Create blank project. Fill in the Project name (the Project slug fills in automatically and becomes part of the project's URL), leave the Visibility Level on Private — the GitLab.com default — check Initialize repository with a README, and click Create project. You now have a live repository with a README; the optional SAST and Secret Detection checkboxes can wait until your code is real.

The visibility choice deserves one sentence: Private means only you (and people you invite) can see it, Internal is only available on self-managed GitLab and means everyone on that server, and Public means the whole internet. Start Private — you can open a project up later, but you cannot un-publish leaked secrets.

How do I clone a GitLab project and push my first commit?

You clone a GitLab project over HTTPS and authenticate with a personal access token instead of your account password — GitLab does not accept account passwords for Git operations. First, set up the token: click your avatar in the upper-right, go to Edit profile > Access > Personal access tokens, open the Generate token dropdown, and choose Fine-grained token (the modern type; the legacy token is the older alternative). Give it the write_repository scope — that covers both pull and push; read_repository alone only allows pulling. Copy the token immediately, because GitLab shows it exactly once.

Now the terminal work, verified against the current docs. Tell Git who you are, clone, commit, and push:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"
git clone https://gitlab.com/your-username/your-project-slug.git
cd your-project-slug
# make a change, e.g. edit README.md
git add .
git commit -m "My first commit"
git push -u origin main

When Git prompts for credentials, enter your GitLab username and paste the personal access token as the password — the docs phrase it exactly that way: use your token as the password when Git prompts for credentials. The -u flag links your local branch to the remote so future pushes are just git push. Refresh your project page and your commit is there.

How do I create a merge request on GitLab?

A merge request is GitLab's name for proposing a branch's changes for review before they land in the main branch — the same concept GitHub calls a pull request. The beginner-safe rhythm is: create a feature branch, push it, then open the merge request from GitLab's UI. In your terminal, run git checkout -b add-homepage, make your change, commit it, and push with git push -u origin add-homepage. Back on the project page, GitLab shows a blue Create merge request prompt above the file list on that branch — click it (or go to Code > Merge requests > New merge request). Write a short title and description, click Create merge request, and when checks pass the merge-request widget shows a Merge button that lands your change.

Two habits separate beginners from teams here: keep each merge request to one idea so reviewers can actually review it, and read the diff yourself before asking anyone else to. GitLab's widget shows pipeline status, approvals, and conflicts in one place, so "merge" is a decision you make with the full picture in front of you.

How do I run my first CI/CD pipeline?

Your first CI/CD pipeline needs exactly one file: .gitlab-ci.yml in the root of your repository — the moment it exists, GitLab runs it on every push. In your project go to Code > Repository > New file, name it .gitlab-ci.yml, and paste a minimal two-stage pipeline:

build-job:
  stage: build
  script:
    - echo "Hello, $GITLAB_USER_LOGIN!"

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

Click Commit changes, then open Build > Pipelines and select the pipeline ID to watch the visual graph: the build job runs first, the test job runs after, and green checkmarks mean both passed. You do not need to set up any infrastructure for this — GitLab.com provides instance runners that execute your jobs by default. When you later need custom environments (a specific OS, a GPU, your own network), that is where self-managed runners and Docker enter; the Docker beginner guide is the right prerequisite for that step, because GitLab runners commonly execute jobs inside containers.

How do I add team members to a GitLab project?

You invite people at Manage > Members > Invite members: enter a GitLab username for someone who already has an account or an email address for someone new, pick a role (Developer is the right default for teammates who will push code), optionally set an Access expiration date for contractors, and click Invite. Roles are the whole access-control story in GitLab — a Reporter can read and comment but not push, a Developer can push and open merge requests, and a Maintainer can change settings — so grant the smallest role that lets the person do their job. Review the member list when someone leaves the team; stale access is how most small projects leak.

Can I run GitLab on my own server?

Yes — and this is GitLab's signature move: the same software that runs GitLab.com installs on your own hardware, so everything in this guide transfers. The official install page presents two beginner-friendly routes: the Linux package (official deb and rpm packages, described as the most mature and scalable method — it is the version GitLab.com itself runs) and the Docker image ("use if you're familiar with Docker"), alongside advanced options like the Helm chart. This branch stays a branch for a reason: a self-managed GitLab needs a real server, backups, and upgrades, so confirm you actually need one first — the what is VPS hosting guide explains what a virtual private server is and when it makes sense, and the usual entry point is a modest VPS with a few gigabytes of RAM.

Sources

• GitLab official documentation, v19.6 (read October 30, 2026): Personal access tokens (avatar > Edit profile > Access > Personal access tokens; fine-grained vs legacy tokens; use the token as the password for Git over HTTPS); CI/CD quick start (.gitlab-ci.yml minimal example; Build > Pipelines; instance runners provided on GitLab.com); Create a project (Create new (+) > New project/repository > Create blank project; visibility Private default on GitLab.com); Creating merge requests; Project members (Manage > Members > Invite members); Installation methods (Linux package vs Docker image).
• TheLinuxCode — "How to Use GitLab: A Complete Step-by-Step Guide for Beginners" (https://thelinuxcode.com/how-to-use-gitlab/) — the fullest beginner arc (account → project → clone → commits → push → branching → merge requests → CI/CD → members); shows older UI navigation, which is why click paths above were re-checked against current docs.
• Nira — "How to Use Gitlab" (https://nira.com/how-to-use-gitlab/) — step-by-step project creation and Git configuration reference.
• GeeksforGeeks — "What Is Gitlab? Complete Guide" (http://www.geeksforgeeks.org/gitlab/) — platform overview, signup flow, and merge-request concepts.
• TheServerSide — "Full Git and GitLab tutorial for beginners" (https://www.theserverside.com/video/Full-Git-and-GitLab-tutorial-for-beginners, January 2026) — 10-step Git + GitLab walkthrough including the access-token-over-HTTPS authentication note.

Frequently asked questions

Is GitLab free?

Yes for getting started — you can sign up for a free GitLab.com account and follow this entire guide (projects, merge requests, CI/CD pipelines with instance runners) without paying anything, which is how every beginner guide in the field, including TheLinuxCode's, begins. GitLab also sells paid tiers with higher limits and enterprise features, but nothing in this guide needs one.

What is the difference between GitLab and GitHub?

Both host Git repositories, but GitLab bundles CI/CD, container registry, and issue tracking into one product (and lets you self-host the same software), while GitHub pairs code hosting with separate Actions for CI and the largest third-party ecosystem. The day-to-day Git workflow — clone, branch, commit, push, review, merge — is identical; only the UI labels differ (merge requests vs pull requests).

What is a GitLab runner?

A runner is the machine that executes your CI/CD jobs — it picks up the scripts in .gitlab-ci.yml and runs them, then reports results back to GitLab. You do not need your own: GitLab.com provides instance runners by default, so your first pipeline runs with zero setup. Self-managed runners become relevant when you need custom environments or your own network.

Should I clone with HTTPS or SSH?

Use HTTPS with a personal access token — it is the simplest path the docs recommend: when Git prompts for credentials, enter your username and paste the token as the password. Do not paste your account password; GitLab no longer accepts it for Git operations. SSH works too but requires generating and registering an SSH key first, which is an extra step beginners can skip.

What is .gitlab-ci.yml?

It is the file that defines your CI/CD pipeline, written in YAML and placed at the root of your repository. Each block names a job, assigns it a stage (like build or test), and lists the script commands the runner executes. Add the file, commit, push — GitLab detects it and runs the pipeline automatically.