🦊 GitLab Platform

Git is the version control engine. GitLab is the platform built on top of it — issues, pipelines, access control, and release management. This page covers the GitLab features you'll use beyond just pushing code.

Issues — Track Work and Bugs

Issues are GitLab's way of tracking tasks, bugs, feature requests, and discussions. Every piece of planned work should start as an issue before code is written.

Creating an issue:

1. Go to your GitLab project → Issues → New Issue
2. Write a clear title — what needs to happen
3. Describe the problem or requirement in the description
4. Assign it to the right person (or yourself)
5. Add a label (see below) and a milestone if relevant
6. Set a due date if there's a deadline

Link a commit or MR to an issue:

GitLab automatically closes an issue when a commit message or MR description contains a closing keyword + the issue number:

# In a commit message
git commit -m "fix: handle null token on login — Closes #42"

# In an MR description
Closes #42
Fixes #38
Resolves #55

When the MR is merged, GitLab closes all linked issues automatically.

Issue boards: GitLab issues can be visualised as a Kanban board under Issues → Boards. Drag cards between columns (Open → In Progress → Review → Done) to track team work at a glance.

Labels & Milestones — Organise Work

Labels are coloured tags you attach to issues and MRs to categorise them. Common label sets:

Create labels at Issues → Labels → New Label. You can filter issues and MRs by label, making it easy to see all open bugs or all backend work.

Milestones group issues and MRs toward a shared goal — typically a sprint or a release version.

1. Go to Issues → Milestones → New Milestone
2. Set a title (e.g., Sprint 12 or v2.1.0) and a due date
3. Assign issues to the milestone — GitLab shows a progress bar as issues close

Forks — Your Own Copy of a Repo

A fork is a personal copy of a repository under your own GitLab namespace. You use forks when you want to contribute to a project you don't have write access to — common in open-source workflows and when contributing to another team's repo.

Fork workflow:

git remote add upstream git@gitlab.company.com:original-team/project.git
git remote -v   # you should now have origin (your fork) and upstream (original)

Keeping your fork in sync with the original:

git fetch upstream
git switch main
git rebase upstream/main    # or: git merge upstream/main
git push origin main        # update your fork on GitLab

Tags & Releases — Mark Versions

Tags are permanent labels on specific commits, typically used to mark release versions. Unlike branch names, tags don't move as you add more commits.

Creating a tag from the terminal:

# Create an annotated tag (recommended — includes message and author)
git tag -a v1.2.0 -m "Release v1.2.0 — adds user profile feature"

# Push the tag to GitLab
git push origin v1.2.0

# Push all tags at once
git push origin --tags

# List all tags
git tag

Creating a tag from the GitLab UI:

1. Go to Repository → Tags → New Tag
2. Enter a tag name (e.g., v1.2.0)
3. Select the branch or commit to tag
4. Add a message and optional release notes

Creating a Release from a tag:

GitLab Releases attach release notes, changelogs, and downloadable assets to a tag. Go to Deployments → Releases → Create Release, select your tag, and fill in the release notes. The release appears on your project's main page and is browseable under Releases.

Branch Protection — Enforce Team Rules

Branch protection rules prevent accidental direct commits to important branches (main, develop) and enforce code review before merging.

Setting up protection:

1. Go to Settings → Repository → Protected Branches
2. Type the branch name (e.g., main) and click Protect
3. Configure who can merge (e.g., Maintainers + Developers) and who can push directly (e.g., No one)

Merge request approvals: go to Settings → Merge Requests to set how many approvals an MR needs before it can merge. You can also require approval from specific people or groups.

MR Advanced Features

Draft MRs (Work in Progress): prefix your MR title with Draft: to signal it's not ready for review yet. GitLab blocks merging until you remove the prefix. Use this to share progress early, get early feedback, or run CI without the pressure of review.

Assignees vs Reviewers:

• Assignee — the person responsible for the MR (usually the author)
• Reviewer — the person asked to review and approve

Assign a reviewer when your MR is ready. They get a notification and the MR appears in their review queue.

Squash commits on merge: under MR settings, enable Squash commits when merging to collapse all your branch commits into a single clean commit on main. Good for keeping main history tidy when feature branches have many "fix typo", "WIP" commits.

Delete source branch: always tick Delete source branch when merge request is accepted. It keeps the remote clean — old branches pile up fast on a busy team.

Rebase on GitLab: if your branch is behind main, GitLab shows a Rebase button on the MR page. Clicking it rebases your branch onto the latest main without needing to do it locally.

Inline comments and suggestions: reviewers can comment on specific lines of code. They can also use the Suggest change feature to propose an exact replacement — the author can apply the suggestion with one click directly from the GitLab UI.

CI/CD Basics — Automated Pipelines

GitLab CI/CD runs automated jobs whenever you push code — building, testing, linting, and deploying without manual steps. It's configured with a file called .gitlab-ci.yml in the root of your repo.

How it works:

• You push a commit or open an MR
• GitLab reads .gitlab-ci.yml and creates a pipeline
• A pipeline is a sequence of stages (build → test → deploy)
• Each stage runs one or more jobs in parallel
• If a job fails, the pipeline stops and the MR is blocked from merging

A minimal example .gitlab-ci.yml:

stages:
  - build
  - test

build-job:
  stage: build
  script:
    - echo "Building the project..."
    # your build command here

test-job:
  stage: test
  script:
    - echo "Running tests..."
    # your test command here

Viewing pipelines: go to CI/CD → Pipelines to see all runs. Click a pipeline to see its stages and jobs. Click a job to see its full log output.

Pipeline status on MRs: GitLab shows the pipeline status directly on the MR page. A green checkmark means all jobs passed. A red X means something failed — click through to the failing job's log to see why.

GitLab CI/CD is a deep topic. For more, see the official GitLab CI/CD documentation.