Skip to content

Fab Academy 2026: Git & GitLab Reference Guide

Overview

This document summarizes the key concepts from the Fab Academy Recitation 1 on Version Control and GitLab, presented by Julian. Git is fundamental infrastructure that powers version control across many tools and platforms—mastering it is one of the most important skills in Fab Academy.

Fab Academy Platforms

Platform Purpose URL
Fab Labs IO Global network platform, single sign-on for all services fablabs.io
GitLab Open-source Git repository hosting (self-hosted by Fab Academy) gitlab.fabcloud.org
Mattermost Chat platform for 2026 cohort collaboration chat.academany.org
Nueval Custom evaluation tool for instructor assessments (shown later in course)

GitLab Login

  1. Go to gitlab.fabcloud.org
  2. Do NOT use the username/password form
  3. Click the "Fab Labs.io" button at the bottom
  4. Log in through Fab Labs IO (single sign-on)
  5. You'll be redirected back to GitLab, now authenticated

Understanding GitLab Structure

Fab Academy Organization

Fab Academy 2026
└── Labs (group)
    └── [Your Lab Name] (e.g., Barcelona, Oulu, Bohol, Zoi)
        ├── students/
        │   └── [your-name]/ ← Your repository
        └── site/ (lab's generic website)

Finding Your URL

  • All student websites: fabacademy.org/2026/people
  • Your URL format: fabacademy.org/2026/labs/[lab-name]/students/[your-name]

Setup Email

Look for an email with subject containing "Fab Academy" from coordination. This contains your repository setup link.

Git Fundamentals

Key Concepts

Term Definition
Working Directory Files you're actively editing on your computer
Staging Area Temporary bucket of files ready to be committed
Commit A saved snapshot of changes with a message
Branch A sequential list of commits (default: main)
Repository All files plus their complete history
Local Repository Git repo on your computer
Remote/Origin Cloud repository (GitLab)

The Git Workflow

Working Directory → Staging Area → Local Repository → Remote Repository
     (edit)          (git add)      (git commit)       (git push)

Working with GitLab Web IDE

Opening the Web Editor

  1. Navigate to your project in GitLab
  2. Click the blue "Code" button
  3. Select "Web IDE" at the bottom
  4. Editor opens with VS Code-like interface

Making Changes

  1. Open a file from the left sidebar
  2. Edit the content
  3. Click the Source Control tab (shows change count)
  4. Review changes (before/after comparison)
  5. Write a commit message
  6. Click "Commit and push to main"
  7. First time: Click "Continue" when asked about default branch

Viewing History

  • Click the commit hash on your project page to see that commit's changes
  • Navigate to Code → Commits to see full history

CI/CD Pipeline (Continuous Integration)

What It Does

Every time you push a commit, GitLab automatically: 1. Reads the .gitlab-ci.yml file 2. Sends instructions to a runner server 3. Builds your website (if using a static site generator) 4. Publishes HTML files to your public URL

The .gitlab-ci.yml File

For plain HTML projects: 

image: alpine:latest

pages:
  script:
    - echo "Nothing to build for HTML"
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

For MkDocs projects: 

image: python:latest

pages:
  script:
    - pip install mkdocs mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Monitoring Pipelines

  • Green checkmark ✓ = Pipeline passed, website deployed
  • Blue circle = Running
  • Red X = Failed (click to view logs and debug)

Important: Only the most recent successful pipeline matters for your website.

Local Git Setup

Installing Git

  • Mac/Linux: Usually pre-installed; verify with git --version
  • Windows: Use Windows Subsystem for Linux (WSL) recommended
  • Installation guide: git-scm.com/downloads

1. Generate a key: 

ssh-keygen -t ed25519 -C "my laptop key"
Press Enter for default location, leave passphrase empty for simplicity.

2. Copy your public key: 

# Mac
cat ~/.ssh/id_ed25519.pub | pbcopy

# Windows (Git Bash)
cat ~/.ssh/id_ed25519.pub | clip

# Linux
cat ~/.ssh/id_ed25519.pub

3. Add to GitLab: - Go to GitLab → Profile → Preferences → SSH Keys - Click "Add new key" - Paste your public key - Save

4. Test connection: 

ssh -T git@gitlab.fabcloud.org
Should return: "Welcome to GitLab, @your-username!"

Alternative: Personal Access Token

Used by some editors like VS Code. Create at: GitLab → Profile → Preferences → Access Tokens

Essential Git Commands

Initial Setup (Once)

# Configure your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Clone Your Repository

# Get the SSH URL from GitLab (Code button → Clone with SSH)
git clone git@gitlab.fabcloud.org:academany/fabacademy/2026/labs/[lab]/students/[name].git

# Move into the project folder
cd [name]

Daily Workflow

# Check status (see what's changed)
git status

# See specific changes
git diff

# Stage specific files
git add filename.html
git add images/photo.jpg

# Stage interactively (review each change)
git add -p

# Commit staged changes
git commit -m "Updated week 2 documentation"

# Push to GitLab
git push

# Pull latest changes (if you edited in Web IDE or another computer)
git pull

Viewing History

# See commit history
git log

# See condensed history
git log --oneline

Emergency Reset

# Discard all local changes and match remote
git reset --hard origin/main
git pull

Nuclear option: If everything is broken, make a backup copy of your folder, delete the repo, clone fresh, and copy your new work back in.

Best Practices

Commit Messages

  • ✅ Good: "Updated week 2 with laser cutter documentation"
  • ✅ Good: "Added hero image to homepage"
  • ✅ Good: "Fixed broken link in navigation"
  • ❌ Bad: "update"
  • ❌ Bad: "stuff"
  • ❌ Bad: "asdfasdf"

Commit Frequency

  • Commit often (saves your work incrementally)
  • Don't need to push after every commit
  • Push at logical breakpoints (end of session, completed section)

File Review Before Committing

Never blindly use git add . — always review what you're adding:

# See what would be added
git status

# Review changes interactively
git add -p

What NOT to Commit

  • Large files (>10MB)
  • Passwords or API keys
  • System files (.DS_Store, Thumbs.db)
  • Build outputs (if using static site generators)

File Size Management

Hard Limits

  • Single commit: 20MB maximum
  • Total repository: 500MB maximum

Image Guidelines

Guideline Target
File size Under 100KB per image
Dimensions 800px maximum width
Format JPEG for photos, PNG for graphics

Optimization Tools

  • ImageMagick: Command-line image processing
  • Image Optim: Mac app for compression
  • TinyPNG: Web service for compression
  • Squoosh: Google's web-based optimizer

Video Guidelines

  • Compress before uploading
  • Target: 1-2MB for short clips
  • Consider embedding from YouTube for longer videos (but risks link rot)

HTML Best Practices

<!-- ✅ Correct: Relative path -->
<a href="../week02/index.html">Week 2</a>
<img src="images/photo.jpg" alt="My photo">

<!-- ❌ Wrong: Absolute URL -->
<a href="https://fabacademy.org/2026/labs/mylab/students/me/week02/">Week 2</a>

File Naming

  • All lowercase
  • No spaces (use hyphens: my-image.jpg)
  • Simple, descriptive names

External Libraries

Download and include locally rather than linking to CDNs:

<!-- ✅ Local copy (preserved forever) -->
<script src="js/library.js"></script>

<!-- ❌ CDN link (may break in future) -->
<script src="https://cdn.example.com/library.js"></script>

Static Site Generators

Advantages: - Write in Markdown (simpler than HTML) - Automatic navigation - Material theme for customization - Easy configuration

Folder Structure: 

project/
├── docs/           ← Your Markdown files
│   ├── index.md
│   └── week01/
├── mkdocs.yml      ← Configuration
└── .gitlab-ci.yml  ← Build instructions

Other Options

  • Hugo: Fast, Go-based generator
  • Docusaurus: React-based, good for documentation
  • Plain HTML: No build step, full control

Templates

Find templates at: gitlab.fabcloud.org/academany/fabacademy/templates/

Troubleshooting

Pipeline Failed

  1. Click the red X on your commit
  2. Click the failed job
  3. Read the log output
  4. Common issues:
  5. Missing .gitlab-ci.yml file
  6. Syntax error in YAML
  7. Missing dependencies

Can't Push

# If you have unpulled changes
git pull
# Then try pushing again
git push

Merge Conflicts

If you edited in both Web IDE and locally: 1. git pull 2. Resolve conflicts in the marked files 3. git add the resolved files 4. git commit 5. git push

SSH Connection Issues

# Test connection
ssh -T git@gitlab.fabcloud.org

# If multiple keys, configure in ~/.ssh/config:
Host gitlab.fabcloud.org
    IdentityFile ~/.ssh/id_ed25519

Quick Reference Card

Action Command
Check status git status
Stage file git add filename
Stage interactively git add -p
Commit git commit -m "message"
Push to remote git push
Pull from remote git pull
View history git log
See changes git diff
Reset to remote git reset --hard origin/main

Resources

  • GitLab Docs: docs.gitlab.com
  • Git Tutorial: git-scm.com/book
  • Neil's Notes: academy.cba.mit.edu
  • Mattermost: chat.academany.org (ask Julian questions!)
  • Templates: gitlab.fabcloud.org/academany/fabacademy/templates

Creating gitlab branch

Initial Machine One-time Setup

  1. Create a new folder called "Groupwork" (or whatever you want to call it) and change directory into "Groupwork" from within terminal
    mkdir Groupwork
    cd Groupwork
  2. Run the following to create a new virtual environment to keep your projects organized
    python3 -m venv venv
  3. Activate the environment
    source venv/bin/activate
  4. Clone the site
    git clone git@gitlab.fabcloud.org:academany/fabacademy/2026/labs/charlotte/site.git
  5. Run the command ls to see the file structure File Structure
  6. Change the directory
    cd site
  7. Run the following command to see if the site is ready to edit
    mkdocs serve --livereload
    Note: On our installation we received the following error: ERROR - Config value 'plugins': The "git-revision-date-localized" plugin is not installed
    Resolved: pip install mkdocs-git-revision-date-localized-plugin

Now your environment is ready to create the new branch

To create a new branch:

  1. make sure you're starting from main
    git checkout main
    git pull origin main

  2. create and switch to your new branch
    git checkout -b adults

  3. push it to GitLab so the remote knows it exists
    git push origin adults

Normal workflow:

  1. Start on your branch
    git checkout adults

  2. Do your work (edit files, add content, etc.)

  3. Stage and commit your changes
    git add .
    git commit -m "description of what you did"

  4. Push to GitLab
    git push origin adults

  5. When ready to go live, merge into main
    git checkout main
    git pull origin main
    git merge adults
    git push origin main

  6. Go back to your branch to keep working
    git checkout adults

Document created from Fab Academy 2026 Recitation 1: Version Control and GitLab Presenter: Julian (IT Manager)