GitLab Projects and Repos

A project in GitLab is the container for everything related to one piece of software — code, issues, pipelines, and documentation. A repository (repo) lives inside a project and holds the actual files and their full history.

Project vs Repository — What Is the Difference?

  ┌──────────────────────────────────────────┐
  │              PROJECT                     │
  │  ┌────────────────────────────────────┐  │
  │  │         REPOSITORY                 │  │
  │  │  (all your code files + history)   │  │
  │  └────────────────────────────────────┘  │
  │  Issues │ Merge Requests │ CI/CD │ Wiki  │
  └──────────────────────────────────────────┘

The repository is the filing cabinet. The project is the entire office around it.

Creating a New Project

Click the + button in the top navigation bar and choose New project. GitLab offers three starting options:

Option	When to Use It
Create blank project	You are starting from scratch
Create from template	GitLab pre-fills files for Rails, Node, Android, etc.
Import project	You are moving code from GitHub, Bitbucket, or a zip file

Project Visibility Options

  Private   → Only you and invited members can see it
  Internal  → Anyone with a GitLab account can see it
  Public    → Anyone on the internet can see it (read only)

Understanding the Repository File View

Once you create a project, the repository page shows a file tree. Each row is either a folder or a file. The right side shows the last commit message that touched that file and when it happened.

  📁 my-project/
  ├── 📁 src/           ← "Add user auth"     2 hours ago
  ├── 📁 tests/         ← "Fix test setup"    1 day ago
  ├── 📄 README.md      ← "Update docs"       3 days ago
  └── 📄 .gitlab-ci.yml ← "Add build stage"   5 days ago

The README File

The README.md file is the welcome page for your project. GitLab renders it automatically below the file list. Write it in Markdown — a simple formatting language where ## Heading makes a heading and **bold** makes text bold.

A good README answers four questions:

What does this project do?
How do I install and run it?
How do I contribute?
What licence does it use?

Cloning a Repository to Your Computer

Cloning downloads a full copy of the repository to your local machine. You can then edit files, run the code, and push changes back to GitLab.

  GitLab                          Your Computer
  ──────                          ─────────────
  📁 my-project (remote)
       │
       │  git clone git@gitlab.com:username/my-project.git
       ▼
                                  📁 my-project (local copy)
                                  All files + full history

Click the blue Clone button on the project page and copy the SSH URL. Then run:

  git clone git@gitlab.com:username/my-project.git

The Three Core Git Actions

Add

Marks changed files for the next save point (commit).

  git add filename.txt       ← stage one file
  git add .                  ← stage all changed files

Commit

Takes a snapshot of the staged files and records it with your message.

  git commit -m "Fix the login error on mobile"

Push

Sends your local commits to GitLab so teammates can see them.

  git push origin main

The Full Local-to-GitLab Workflow

  Edit file
     ↓
  git add .
     ↓
  git commit -m "describe what you changed"
     ↓
  git push origin main
     ↓
  GitLab stores the new snapshot ✅

Pulling Changes From GitLab

When a teammate pushes changes, your local copy becomes out of date. Run git pull to download and apply their changes to your local copy.

  Teammate pushes update to GitLab
           ↓
  You run: git pull origin main
           ↓
  Your local copy is now up to date

Project Settings — Key Options

Renaming a Project

Go to Settings → General → Project name. GitLab automatically redirects old URLs to the new name, so existing links keep working.

Archiving a Project

Archiving makes a project read-only. No one can push code or open issues. Use this for finished or abandoned projects you want to preserve but not actively maintain.

Deleting a Project

Deletion is permanent. GitLab asks you to type the project name to confirm before it removes everything. Owners must wait 7 days by default before deletion completes (configurable by admins).

Forking a Project

Forking creates your own copy of someone else's project under your namespace. You can modify your fork freely without affecting the original.

  Original project (owner: sara)
         ↓  Fork
  Your copy (owner: you) ← make changes here
         ↓  Merge Request
  Sara reviews and merges your improvement into her original

Forking is the standard way to contribute to public open-source projects on GitLab.

Starring a Project

Click the star icon on any project page to bookmark it. Starred projects appear in your Explore → Starred tab. Stars also act as a popularity indicator for public projects.

Previous lesson

Back to course

Next lesson