GitLab Basics

Page 04 — What GitLab adds on top of Git, and how to work with it day to day.

What GitLab is

GitLab is a platform built around Git repositories. Git stores the history. GitLab manages the repo on a server and adds workflow on top of it:

• Web UI to browse code and history
• Merge requests for reviewing and merging branches
• Pipelines for automated checks (lint, test, build, deploy)
• Access controls and protected branches
• Issues and project management

Add your SSH key to GitLab

Show your public key:

cat ~/.ssh/id_ed25519.pub

Paste it into GitLab → Preferences → SSH Keys. Then test the connection:

ssh -T git@your-gitlab-host

Normal workflow

git checkout main
git pull origin main
git checkout -b feature/change
# edit files
git add .
git commit -m "Describe change"
git push -u origin feature/change

Then in GitLab:

1. Open a Merge Request from your branch to main
2. Review the diff — make sure it only contains what you intended
3. Check that the pipeline passes
4. Merge when approved

Merge Request

A Merge Request (MR) is GitLab's review flow for combining your branch into another branch, usually main. You use it so:

• Others can review and comment on your changes
• Automated checks (pipeline) can run before the code is merged
• History stays clean and auditable

Useful MR terms:

• protected branch — direct push is blocked; changes must go through an MR
• merge blocked — pipeline failing, approvals required, or a conflict exists
• fork — a separate copy of the repo under a different namespace

Pipeline

A pipeline is a set of automated jobs that run on every push, defined in .gitlab-ci.yml. Common jobs include linting, syntax checks, tests, and build steps.

If a pipeline fails, GitLab is telling you something needs fixing before the MR can merge. Check the job output for the specific error.

Common pipeline failures:

• Syntax error in a file
• Linting problem (code style, YAML format)
• Test failure
• Missing CI/CD variable (check project settings)
• Runner offline or unavailable

Common problems

Auth failed

• SSH key not added to your GitLab profile
• Wrong remote URL (HTTPS when you need SSH, or vice versa)
• Logged into the wrong account

Push rejected

• Remote has changes you do not have — pull or rebase first
• Trying to push directly to a protected branch
• Insufficient permissions on the project

Check and change remotes

git remote -v

Shows which remote URLs your repo uses. Check this when auth issues are unclear.

Switch from HTTPS to SSH:

git remote set-url origin git@host:group/repo.git

Personal Access Token (HTTPS auth)

If you can't use SSH keys (e.g. on a shared machine, or when cloning in a script), use a Personal Access Token (PAT) for HTTPS authentication.

Create a PAT in GitLab

1. Go to your GitLab profile: User menu → Edit profile → Access Tokens
2. Give the token a name (e.g. laptop-cli)
3. Set an expiry date
4. Select the minimum required scopes:
   • read_repository — clone and pull only
   • write_repository — push and create branches
   • api — full API access (only needed for scripts/automation)
5. Click Create personal access token and copy the value — you only see it once

Using a PAT to clone

# Embed token directly in the URL (not recommended for interactive use — stored in shell history)
git clone https://your-token@gitlab.internal/group/repo.git

# Better: use the username + token prompt
git clone https://gitlab.internal/group/repo.git
# Git will prompt for username (enter your GitLab username)
# and password (enter your PAT — not your account password)

Credential helper — avoid re-entering the PAT

# Store credentials in plaintext (simplest — acceptable on private machines)
git config --global credential.helper store
# After your next push/pull with credentials, Git stores them in ~/.git-credentials

# On macOS — use the system keychain
git config --global credential.helper osxkeychain

# On Linux — use libsecret (GNOME keyring)
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret

The store helper saves credentials unencrypted to ~/.git-credentials. On a shared or multi-user machine, use a keychain-based helper instead.

Create MR from the terminal

You can create a GitLab Merge Request directly from the git push command — no browser required. GitLab prints the MR URL in the push output.

# Push and create an MR in one command
git push -o merge_request.create origin feature/add-chrony-role

# Push, create MR, and set the target branch (default is usually main)
git push \
  -o merge_request.create \
  -o merge_request.target=main \
  origin feature/add-chrony-role

# Create as a Draft MR (blocks accidental merge until ready)
git push \
  -o merge_request.create \
  -o merge_request.target=main \
  -o merge_request.title="Draft: Add chrony NTP role" \
  origin feature/add-chrony-role

# Assign to a reviewer by username
git push \
  -o merge_request.create \
  -o merge_request.assign=johndoe \
  origin feature/add-chrony-role

GitLab will print the MR URL after a successful push. You can share this URL in Slack, a ticket, or a PR comment immediately.