My First GitHub Project: From a Local Folder to GitHub Using Git and SSH

Introduction

Reproducibility breaks long before model architecture does. In our research clusters, the most frequent failure point for new AI engineers is not gradient divergence or hardware constraints. It is a broken local-to-remote pipeline. When an experiment lives only in a desktop folder, it dies the moment the machine reboots, the environment drifts, or a teammate needs to verify results.

This article documents the exact workflow we use to transition a raw local directory into a secure, version-controlled GitHub repository using Git and SSH. We treat the repository as the single source of truth for code, configuration, and environment manifests. By establishing cryptographic identity upfront and automating validation before every push, we eliminate credential friction, enforce discipline on large artifacts, and create an audit trail that survives hardware turnover.

Why This Matters

AI development introduces unique versioning pressures. A single training run depends on exact Python package versions, hardware-specific CUDA binaries, and configuration files that dictate hyperparameters. Manual copying or ad-hoc sharing destroys reproducibility. Password-based HTTPS workflows fail in headless training servers and CI/CD runners because they cannot handle interactive credential prompts.

SSH resolves this by replacing passwords with asymmetric cryptography. The local machine signs requests with a private key, and GitHub verifies the signature using the public key. This enables passwordless, automated, and auditable pushes. For AI teams, this means training scripts can trigger remote syncs without human intervention, configuration drift is caught early, and every experiment commit maps directly to a verifiable code state.

How It Works

The pipeline moves from local initialization through cryptographic authentication to remote reference synchronization. Git tracks changes as object snapshots, compresses deltas, and prepares a packfile for transfer. SSH handles the secure channel, verifying host identity and authenticating the client via Ed25519 signatures. GitHub receives the packfile, updates remote branches, and evaluates webhook triggers.

flowchart TD
    subgraph Local_Workspace["Local Development Environment"]
        A[AI Project Directory] --> B[git init & Configuration]
        B --> C[Stage Code & Configs]
        C --> D[Pre-commit Validation]
    end

    subgraph Auth_Layer["SSH Cryptographic Handshake"]
        D --> E[Load Ed25519 Private Key]
        E --> F[Agent Forwarding & Host Verification]
        F --> G[Asymmetric Signature Exchange]
    end

    subgraph Remote_Sync["GitHub Infrastructure"]
        G --> H[Secure Tunnel Establishment]
        H --> I[Remote Reference Update]
        I --> J[Trigger CI Pipeline]
    end

    D -->|Validation Failure| K[Abort Push & Report Errors]
    G -->|Auth Success| H

The flow executes in four phases. First, Git initializes the object database and configures user identity. Second, changes enter the staging area where pre-commit hooks run static analysis, size checks, and environment validation. Third, SSH reads the private key, negotiates ciphers with GitHub, and signs the connection request. Fourth, Git streams the compressed packfile over the encrypted tunnel, GitHub updates branch pointers, and webhooks fire downstream automation. Any validation failure halts the pipeline before network transmission, preventing corrupted or oversized commits from reaching the remote.

Core Concepts

Git operates as a content-addressable filesystem. Every file, directory, and commit becomes a SHA-1 object stored in .git/objects. The staging area (index) acts as a blueprint for the next commit, allowing granular control over what enters version history. For AI projects, this separation is critical: you can stage configuration updates while excluding temporary training artifacts.

SSH authentication relies on key pairs. The private key remains on the local machine, never transmitted. The public key lives on GitHub. During connection, GitHub sends a challenge; the client signs it with the private key. GitHub verifies the signature against the stored public key. Ed25519 is the current standard due to its compact size, deterministic signatures, and resistance to side-channel attacks.

Git remotes are simply URL references to external repositories. origin points to GitHub. When you push, Git calculates the minimal delta between local and remote histories, compresses it, and streams it. GitHub applies the delta, updates branch references, and evaluates repository settings like branch protection rules and webhook subscriptions.

Examples & Code Walkthrough

Below is a production-grade scaffolding script we use to initialize AI projects with Git, SSH, and automated validation. It avoids boilerplate, enforces defensive checks, and structures the workspace for reproducible machine learning workflows.

#!/usr/bin/env python3
"""
setup_ai_repo.py - Initializes a Git-tracked AI project with SSH authentication
and pre-commit validation hooks. Designed for reproducible research environments.
"""
import os
import subprocess
import sys
from pathlib import Path
from typing import Optional

REQUIRED_DIRS = ["src", "configs", "data/manifests", "scripts", "models"]
GIT_IGNORE_CONTENT = """# Environments
.venv/
env/
__pycache__/
*.pyc

# ML Artifacts & Checkpoints
*.pth
*.ckpt
*.onnx
models/*
!models/.gitkeep

# Large Datasets & Cache
data/raw/
data/processed/
.cache/
*.parquet
*.h5

# OS & Editor
.DS_Store
Thumbs.db
.vscode/
.idea/
"""

PRE_COMMIT_HOOK = """#!/usr/bin/env bash
set -euo pipefail

# Pre-commit validation for AI projects
# Checks for oversized files, missing requirements, and config syntax

MAX_FILE_SIZE_MB=50
REQUIREMENTS_FILE="requirements.txt"

echo "Running pre-commit checks..."

# 1. Block large files that break Git performance
LARGE_FILES=$(git diff --cached --name-only | xargs -I {} sh -c 'size=$(stat -f%z "{}" 2>/dev/null || stat -c%s "{}" 2>/dev/null); if [ "$size" -gt $((MAX_FILE_SIZE_MB * 1024 * 1024)) ]; then echo "{}"; fi')
if [ -n "$LARGE_FILES" ]; then
    echo "ERROR: Files exceeding ${MAX_FILE_SIZE_MB}MB detected:"
    echo "$LARGE_FILES"
    echo "Use DVC or external storage for model weights and datasets."
    exit 1
fi

# 2. Validate requirements.txt exists and is not empty
if [ ! -f "$REQUIREMENTS_FILE" ] || [ ! -s "$REQUIREMENTS_FILE" ]; then
    echo "WARNING: $REQUIREMENTS_FILE is missing or empty. Environment may not be reproducible."
fi

# 3. Basic Python syntax check on staged files
STAGED_PY=$(git diff --cached --name-only | grep -E '\\.py$' || true)
if [ -n "$STAGED_PY" ]; then
    echo "$STAGED_PY" | xargs python3 -m py_compile 2>/dev/null
    if [ $? -ne 0 ]; then
        echo "ERROR: Python syntax validation failed on staged files."
        exit 1
    fi
fi

echo "Pre-commit checks passed."
exit 0
"""

def run_cmd(cmd: list[str], check: bool = True) -> subprocess.CompletedProcess:
    """Execute shell command with error handling and output capture."""
    try:
        return subprocess.run(cmd, check=check, capture_output=True, text=True)
    except subprocess.CalledProcessError as e:
        print(f"Command failed: {' '.join(cmd)}")
        print(e.stderr)
        sys.exit(1)

def setup_git_repo(base_dir: Path) -> None:
    """Initialize Git repository and configure local identity."""
    print("Initializing Git repository...")
    run_cmd(["git", "init", str(base_dir)])
    run_cmd(["git", "config", "user.email", "researcher@lab.local"])
    run_cmd(["git", "config", "user.name", "AI Engineer"])
    run_cmd(["git", "config", "core.autocrlf", "input"])

def setup_ssh_keys(base_dir: Path) -> Optional[Path]:
    """Generate Ed25519 SSH key pair if not already present."""
    ssh_dir = Path.home() / ".ssh"
    key_path = ssh_dir / "id_ed25519_ai"
    
    if key_path.exists():
        print(f"SSH key already exists at {key_path}. Skipping generation.")
        return key_path
    
    print("Generating Ed25519 SSH key pair...")
    run