Getting Started with GitLab — Projects, Groups, Permissions, and Navigation

This guide helps you onboard quickly to GitLab. You will learn how GitLab is organized (projects and groups), how access works (roles and permissions), and how to navigate the interface to find issues, merge requests, pipelines, and settings. By the end, you can confidently create a project, invite teammates, and ship changes with merge requests.


What you'll learn

  • Projects — repositories, issues, merge requests, CI/CD.
  • Groups — organizing projects, subgroups, and shared settings.
  • Permissions — roles, protected branches, code approvals.
  • Navigation — where to find common features and settings.
  • Quick start — create a project and your first merge request.

Projects

Definition: A project is the core unit in GitLab that contains your repository, issues, merge requests, CI/CD pipelines, package/registry artifacts, and settings. You can create a project from scratch, import from GitHub/Git, or use a template.

Why it matters: Projects are the atomic unit for shipping software. Most daily actions—committing code, opening issues, creating merge requests, and running pipelines—happen inside a project.

Create a new project

  1. From the top bar, select New project.
  2. Choose Create blank project (or import), name it, pick visibility (Private/Internal/Public).
  3. Initialize with a README to make the repo immediately clonable.

Tip: Use semantic, discoverable names (e.g., payments-service).

Clone the project

  • HTTPS: git clone https://gitlab.com/<namespace>/<project>.git
  • SSH: git clone git@gitlab.com:<namespace>/<project>.git

Inside a project you'll find left-side navigation for Code, Issues, Merge requests, CI/CD, Security (if enabled), Packages and registries, and Settings.

Example workflow

  1. Create a feature branch.
  2. Commit changes and push.
  3. Open a merge request and request reviews.
  4. Wait for CI to pass, then merge to main.
git checkout -b feature/signup-rate-limit
# edit files
git add .
git commit -m "feat: add rate limit to signup API"
git push -u origin feature/signup-rate-limit

Groups

Definition: Groups organize multiple projects under a single namespace. They let you share members, permissions, CI variables, and policies across projects. Groups can contain subgroups for large organizations.

Why it matters: Groups standardize how teams work. You can enforce branch protection, approvals, and secrets once and reuse them across projects.

Common use cases

  • Own all product repos under one group for consistent access control.
  • Store shared CI/CD variables (e.g., cloud creds) at the group level.
  • Separate business units with subgroups and inherited permissions.

Example: group-level CI variable

Define AWS_REGION at the group level and reference it in multiple projects' pipelines:

# .gitlab-ci.yml
variables:
  AWS_DEFAULT_REGION: "$AWS_REGION"  # defined in Group → Settings → CI/CD → Variables

Permissions (Roles & Branch Protection)

GitLab uses role-based access control at the project and group levels. Typical roles:

  • Guest: Read issues/boards, create issues.
  • Reporter: Read code, pull repo, view pipelines.
  • Developer: Push to non-protected branches, create merge requests.
  • Maintainer: Manage settings, protected branches, runners, approvals.
  • Owner (group-level): Full control over group and projects.

Best practice: Grant the least privilege needed. Most contributors should be Developer. Limit Maintainer to a few trusted engineers.

Protected branches & approvals

  • Protect main/release branches so only Maintainers can merge.
  • Require approvals in Settings → Merge requests (e.g., 1–2 reviewers).
  • Enable code owners to enforce domain-specific reviews.

Example: CODEOWNERS

# CODEOWNERS
/backend/   @team-backend
/frontend/  @team-frontend
*.tf        @team-infra


Quick Start: Your First Merge Request

  1. Create a new project and initialize with README.
  2. Clone locally and create a feature branch: git checkout -b feature/hello.
  3. Commit a change, push: git push -u origin feature/hello.
  4. Open a Merge Request from your branch to main.
  5. Request review, pass pipeline, and merge.

Optional: set branch protection and required approvals before merging to enforce quality.

Example commands

# after cloning
cd my-project

echo "Hello GitLab" >> README.md
git add README.md
git commit -m "docs: add hello section"

# create feature branch and push
git checkout -b docs/hello
git push -u origin docs/hello

Next Steps

Consider enabling Merge request approvals and Code Owners for stronger governance as your team grows.


Tags:

Post a Comment

0 Comments