Git & GitLab Onboarding Guide

Welcome to the TechLit Africa team! This guide will help you set up your terminal environment so you can contribute to our lesson plans, websites, and system tools safely.

1. GitLab Account Setup

Before you start working in the terminal, you need a GitLab account.

1. Register: Go to GitLab.com and create a free account.
2. Join the Group: Once your account is ready, request GitLab write access on WhatsApp. Provide your GitLab username, and you will be added to the techlit-africa workspace or specific project.

2. GitLab Authentication

You have two ways to connect your computer to GitLab. Choose the one that works best for your workflow.

Option 1: SSH (Recommended)

SSH uses a “key pair” to prove your identity. Your private key stays on your machine, and your public key goes to GitLab.

Generate your key

Run this exact command to create a secure connection key. Note the -f flag—this ensures the key is saved where it won’t be deleted.

# Create the secure folder
mkdir -p /srv/public/teachers/denis/guest/.ssh

# Generate the key
ssh-keygen -t ed25519 -f /srv/public/teachers/denis/guest/.ssh/id_ed25519 -C "denis@techlitafrica.org"

Add the key to GitLab

1. View the key content:

   cat /srv/public/teachers/denis/guest/.ssh/id_ed25519.pub
2. Copy the output (the long string starting with ssh-ed25519).
3. Paste in GitLab: Navigate to Preferences → SSH Keys → Add new key. Paste your key and click “Add key”.

Verify the connection

Test the handshake by explicitly telling the computer to use your persistent key:

ssh -i /srv/public/teachers/denis/guest/.ssh/id_ed25519 -T git@gitlab.com

If you see Welcome to GitLab, @username!, you are ready to go.

Option 2: Personal Access Token (PAT)

If you prefer not to use SSH, you can use a Personal Access Token (PAT) to authenticate your Git commands over HTTPS.

1. Create your token:

   • Go to GitLab → Preferences (top right) → Access Tokens.
   • Click Add new token.
   • Name: “TechLit Laptop”.
   • Scopes: Select read_repository and write_repository.
   • Click Create personal access token and copy the string immediately. Store this safely—you won’t see it again.

2. Usage: When you git clone or git push a repository using an HTTPS URL, Git will ask for your username and password:

   • Username: Your GitLab username.
   • Password: Your newly created PAT.

The Golden Rule: Back Up Before You Edit

If you are about to try a Git command you don’t fully understand, or you’re doing a complex merge, always make a local duplicate of your project folder first. While Git is excellent at tracking history, a messy merge or an accidental file deletion can be stressful when you’re just starting out. A quick local copy gives you a 100% safe “undo button.”

# Navigate to your projects directory
cd /srv/public/teachers/denis/guest/projects/

# Duplicate your project folder as a safety backup before experimenting
cp -r websites websites-backup-before-git

# If everything goes completely wrong, you can easily restore it:
rm -rf websites
mv websites-backup-before-git websites

3. Working with Repositories

We keep all our projects organized in a central folder.

mkdir -p /srv/public/teachers/zigzag/guest/projects
cd /srv/public/teachers/zigzag/guest/projects

Cloning a Project

Choose one of our core repositories to start:

• techlit-africa/docs
• techlit-africa/websites
• techlit-africa/sheets
• techlit-africa/shell

git clone git@gitlab.com:techlit-africa/docs.git

4. Branching & Committing

Never work directly on the main branch. This ensures our production files stay clean while you experiment.

cd shell
# Create a "feature branch" for your task
git checkout -b feature/optimize-backup-script

Keep your branch current

If you haven’t worked on your feature branch for a few days, the main branch has likely moved forward. Keep your branch clean and conflict-free by rebasing:

# Update your local main
git switch main
git pull origin main

# Switch back to your feature branch
git switch feature/optimize-backup-script

# Rebase your changes on top of the updated main
git rebase main

5. Keeping Your Work Safe

Rule: If it isn’t pushed to GitLab, it doesn’t exist.

1. Commit early: Save your progress frequently with short, clear messages.

   git add .
   git commit -m "Update backup instructions for zigzag user"
2. Push immediately: Send your branch to GitLab so it’s backed up.

   git push origin feature/optimize-backup-script

6. Opening a Merge Request

Once your work is pushed, go to the project on GitLab and click the “Create Merge Request” button. This notifies the team that your changes are ready for review!

7. Crucial Warnings