Ice-GitHub-Doku

Portable Build-Script for automated GitHub Pages generation with integrated TruffleHog security scanning.

Scans all public repositories for leaked secrets, fetches README content, and generates a complete Jekyll site (just-the-docs theme) — ready to push to <username>.github.io.

Features

• TruffleHog Security Gate — Scans all repos for verified secrets before building; auto-installs if not present
• Automatic Repo Discovery — Finds all public source repos via GitHub API
• Category Mapping — Configurable repo-to-category mapping via categories.conf
• README Fetching — Pulls and sanitizes README content for each project page
• Jekyll Generation — Generates _config.yml, Gemfile, category pages, project pages, and index.md
• Dry-Run Mode — Generate without pushing to verify output
• Portable — Runs on any Linux/macOS with Bash 4+, git, gh, jq, curl

Quick Start

1. Clone this repo

git clone https://github.com/icepaule/Ice-GitHub-Doku.git
cd Ice-GitHub-Doku

2. Create a GitHub Token

Go to github.com/settings/tokens/new and create a token with these scopes:

Scope	Purpose
repo	Clone/push to the site repository
read:org	TruffleHog org-wide secret scanning

3. Configure the .env file

cp .env.example .env
# Edit .env and paste your token:
nano .env

The .env file is automatically loaded by the script and excluded from git via .gitignore.

4. Test with dry-run

chmod +x build-ghpages.sh
./build-ghpages.sh --dry-run

5. Build and push

./build-ghpages.sh

Prerequisites

Tool	Purpose	Install
bash 4+	Script runtime	Pre-installed on most systems
git	Repository operations	apt install git
gh	GitHub CLI (API, clone, push)	cli.github.com
jq	JSON processing	apt install jq
curl	HTTP requests	apt install curl
base64	README content decoding	Part of coreutils
trufflehog	Secret scanning	Auto-installed by the script

One-liner install (Debian/Ubuntu)

apt update && apt install -y git jq curl
# gh CLI:
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
  | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
apt update && apt install -y gh

TruffleHog is installed automatically on first run.

Usage

Usage: build-ghpages.sh [OPTIONS]

Options:
  --dry-run       Generate site without pushing to GitHub
  --user USER     GitHub username (default: icepaule)
  --skip-scan     Skip TruffleHog security scan
  -h, --help      Show this help message

Environment Variables

All configuration can be overridden via the .env file or environment variables:

Variable	Default	Description
GH_TOKEN	(required)	GitHub Personal Access Token
GITHUB_USER	icepaule	GitHub username
SITE_REPO	<user>.github.io	Target site repository
CLONE_DIR	/tmp/<site-repo>	Local clone directory
CATEGORIES_CONF	./categories.conf	Path to category mapping

Examples

# Standard build
./build-ghpages.sh

# Dry-run (generate without push)
./build-ghpages.sh --dry-run

# Different user
./build-ghpages.sh --user another-user

# Skip security scan (faster, not recommended)
./build-ghpages.sh --skip-scan

# Override via environment
CLONE_DIR=/opt/site ./build-ghpages.sh --dry-run

Build Phases

The script runs 9 sequential phases:

Phase	Name	Description
0	Dependency Check	Verifies all tools; auto-installs TruffleHog
1	Authentication	Validates GitHub token from .env or environment
2	TruffleHog Scan	Scans all repos for verified leaked secrets
3	Repo Discovery	Fetches public source repos via gh repo list
4	Category Mapping	Loads categories.conf; generates default if missing
5	README Fetching	Downloads and sanitizes README for each repo
6	Jekyll Generation	Creates _config.yml, pages, and index.md
7	Git Operations	Clones site repo, copies content, commits, pushes
8	Summary	Prints all project URLs grouped by category

TruffleHog Security Gate (Phase 2)

• Attempts org-wide scan first: trufflehog github --org=<user> --only-verified
• Falls back to per-repo scanning if org scan fails
• Generates a JSON report at /tmp/trufflehog-report-<timestamp>.json
• Interactive mode: Prompts to continue or abort on findings
• Non-interactive mode (CI/cron): Aborts on any finding

Category Configuration

Edit categories.conf to map repositories to categories:

# Format: REPONAME|CATEGORY_KEY
IcePorge|security
IceHomeAssist|homeautomation
Ice-MTastik|mesh
IceTimereport|data
followmysun|hardware

Available category keys:

Key	Display Name
security	Security & Malware Analysis
homeautomation	Home Automation & Networking
mesh	Mesh & Communication
data	Data & Tools
hardware	Hardware & ESP32

Repos not listed in categories.conf are discovered but skipped with a warning, making it easy to identify new repos that need categorization.

Generated Site Structure

<site-repo>/
├── _config.yml          # Jekyll config (just-the-docs dark theme)
├── Gemfile              # Ruby dependencies for GitHub Pages
├── index.md             # Homepage with project table by category
└── projects/
    ├── security.md      # Category parent page
    ├── IcePorge.md      # Project page with README content
    ├── IcePorge-Cockpit.md
    └── ...

Each project page includes:

• Repository description
• Link to GitHub source
• Full sanitized README content

Deploying to Another Server

1. Clone this repo
2. Install prerequisites (see above)
3. Create .env with your GitHub token
4. Adjust categories.conf for your repos (or delete it — a default will be auto-generated)
5. Run ./build-ghpages.sh --dry-run to verify
6. Run ./build-ghpages.sh to push

Automation (Cron)

# Rebuild site daily at 2:00 AM
0 2 * * * cd /opt/Ice-GitHub-Doku && ./build-ghpages.sh >> /var/log/ghpages-build.log 2>&1

Note: In non-interactive mode (cron), the script aborts if TruffleHog finds verified secrets.

File Overview

File	Description
build-ghpages.sh	Main build script
categories.conf	Repo-to-category mapping
.env.example	Template for environment configuration
.env	Your local configuration (git-ignored)
.gitignore	Excludes .env and build artifacts

License

MIT