Skip to content
Check out our first blog! Read the Git & GitLab Onboarding Guide
`CTRL K`

Blogs
Git & GitLab Onboarding: Working Safely on TechLit Computers

# Git & GitLab Onboarding: Working Safely on TechLit Computers

May 21, 2026·
Waceke Mwangi
,
Denis

Welcome to the TechLit Africa contributor team! This guide will walk you through setting up your terminal environment on our workstations. Because our default user home is reset on logout, we must use specific persistent paths to ensure your security keys and code projects are never lost.

⚠️ CRITICAL: PERSISTENT vs. EPHEMERAL STORAGE On all standard TechLit computers, the default home directory (`~` or `/home/guest`) is wiped completely every time you log out or the system resets. To prevent losing your work, you must use the persistent storage area at `/srv/public/`.
Note on Usernames: In the examples below, we use the name `denis`. This is a placeholder. Please replace `denis` with your actual TechLit username (e.g., `/srv/public/teachers/amina/guest/`) whenever you type a command.

## Phase 1: 🔑 Environment & Key Provisioning

> Objective: Setup your GitLab account, generate persistent security keys, and configure your global Git identity. Estimated time: 10 minutes

### 1.1 GitLab Account Setup

Before you start working in the terminal, you need a GitLab account to identify your contributions.

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.

### 1.2 Persistent SSH Configuration

To connect to GitLab without a password, we generate an SSH key. We store this in your persistent folder so it survives a logout.

Action Commands:

    # 1. Create the secure folder (Use your actual username instead of 'denis')
    mkdir -p /srv/public/teachers/denis/guest/.ssh

    # 2. Cd into your persistent guest directory
    cd /srv/public/teachers/denis/guest

    # 3. Generate the key
    ssh-keygen -t ed25519 -f .ssh/id_ed25519 -C "denis@techlitafrica.org"

    # 4. Link for GitLab Access (Removes need for -i flag)
    ln -s /srv/public/teachers/denis/guest/.ssh/id_ed25519 /srv/guest/gitlab_ssh

Verification Step: 🔍

Visual Checkpoint:

### 1.3 Git Identity Setup

Git needs to know who is making changes so that your name appears correctly in the project history.

Action Commands:

    # Set your name and email
    git config --global user.name "Denis"
    git config --global user.email "denis@techlitafrica.org"

Note: Global Git configuration is stored in `~/.gitconfig`, which is wiped on logout. To make your identity persistent, you can symlink it to your persistent folder: `ln -s /srv/public/teachers/denis/guest/.gitconfig ~/.gitconfig`

Verification Step: 🔍

    git config --list

## Phase 2: 💡 Local Workspace & The 3-Stage Pipeline

> Objective: Create safety backups, clone the project, and master the local saving cycle. Estimated time: 15 minutes

### 2.1 🛡️ Safe Folder Backups: Your Manual Undo Button

Before practicing Git commands, always make a local duplicate of your folder. This is your 100% safe “undo button” if a command gets confusing.

Action Commands:

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

    # 2. Duplicate your project folder before experimenting
    cp -r websites websites_backup

### 2.2 🔍 The “Git Status” Mantra

Think of `git status` as the terminal user’s eyes. Run it before you add a file, after you stage it, and right before you commit. If you ever feel lost, `git status` is the first command you should type.

### 2.3 Project Cloning

Pull the `websites` repository from GitLab into your persistent projects folder.

Action Commands:

    git clone git@gitlab.com:techlit-africa/websites.git
    cd websites
    ls

Visual Checkpoint:

### 2.4 Saving Your Work: The Three Stages

Git uses a holding zone to help you organize what you save.

1. Modified: You have edited a file (e.g., `src/main.js`) but haven’t told Git to save it yet.
2. Staged (`git add`): You have picked which changes you want to include in your next save. Think of this as putting files into a “to-be-saved” box.
3. Committed (`git commit`): You have permanently saved the snapshot of your staged files to your local history.

Branching & Staging:

        %%{init: { 'theme': 'default', 'themeVariables': { 'fontSize': '28px' }}}%%
    graph LR
        subgraph Remote["GitLab (Remote Server)"]
            RM[main branch]
            RFB[remote branch]
            MR{Merge Request}
        end

        subgraph Local["Your dev computer (Persistent)"]

            LM[main branch]
            FB[feature-branch]

            Edit[Edit Files] --> Modified(Modified)
            Modified -- "git add" --> Staged(Staged)
            Staged -- "git commit" --> Committed(Committed)
        end

        RM -- "git clone" --> LM
        LM -- "git switch -c feature-branch" --> FB
        FB --> Edit
        Committed -- "git push" --> RFB
        RFB -- "Open MR" --> MR
        MR -- "Merged" --> RM

## Phase 3: 🚀 Team Sync & Upstream Collaboration

> Objective: Master feature branching, keep your work current, and share changes via Merge Requests. Estimated time: 15 minutes

### 3.1 Feature Branching Workflow

We never edit the `main` branch directly. We use Feature Branches to keep our production code stable.

Action Commands:

    # 1. Start with the latest code
    git switch main
    git fetch origin
    git pull origin main

    # 2. Create your experimental branch
    git switch -c feature/add_new_feature

Visual Checkpoint:

### 3.2 🔍 Keeping Your Branch Current

If you haven’t worked on your feature branch for a few days, rebase it to include the latest team changes.

Action Commands:

    git switch main
    git pull origin main
    git switch feature/add_new_feature
    git rebase main

Visual Checkpoint:

### 3.3 Pushing Changes & Opening an MR

Once you have committed your work locally, send it to GitLab to share it with the team.

Action Command:

    git push origin feature/add_new_feature

Visual Checkpoint:

### 3.4 ⚠️ Troubleshooting & Escape Hatches

- The Escape Hatch: If a rebase or merge becomes confusing, go back to safety with `git rebase --abort`.
- Clean Workspaces: Always check your `.gitignore` to ensure temporary files aren’t being tracked.
- The snapshot rule: Anything left in `~/` or `/home/guest` disappears forever on logout. Always verify your path with `pwd`.

Congratulations! You are now ready to contribute safely and effectively to the TechLit Africa project.