thgtoa/docs/guide/dev-workflow.md

Development

Overview

This repository now includes an automated workflow that handles PDF generation, verification, and distribution with the following features:

??? Note "How the pipeline works"

1. **Automatic PDF Generation** - Builds both light and dark mode PDFs from MkDocs source
2. **SHA256 Hash Generation** - Creates hash files for integrity verification
3. **GPG Signature Signing** - Signs all PDFs and hash files with repository GPG key
4. **VirusTotal Scanning** - Automatically scans PDFs and updates release notes
5. **Release Automation** - Packages everything into GitHub releases

Workflow Architecture

1. Build PDF Workflow (build-pdf.yml)

Trigger: Push to main, pull requests, or manual dispatch

??? Note "Steps"

- Checkout repository
- Set up Python 3.13 and MkDocs Material
- Install Chromium browser
- Generate both light and dark mode PDFs
- Create SHA256 hash files
- Sign all files with GPG
- Upload artifacts to GitHub Actions
- Publish release

2. VirusTotal Scan Workflow (vt-scan.yml)

Trigger: Push to main, tags, or manual dispatch (runs after build-pdf)

??? Note "Steps"

- Download PDF artifacts from build workflow
- Scan both PDFs with VirusTotal API
- Extract scan results and generate report links
- Update release notes with VT scan status and URLs

File Structure

After a successful build, the repository will contain:

.../
├── export/
│   ├── thgtoa.pdf              # Light mode PDF
│   ├── thgtoa-dark.pdf         # Dark mode PDF
│   ├── thgtoa.pdf.sig          # GPG signature (light)
│   └── thgtoa-dark.pdf.sig     # GPG signature (dark)
├── thgtoa.pdf.sha256           # Hash file (light)
├── thgtoa-dark.pdf.sha256      # Hash file (dark)
├── sha256sum-light.txt         # Combined hash file
└── scripts/
    ├── build_guide_pdf.py      # PDF generation script
    └── verify_pdf.py           # Verification utility

Security Features

1. SHA256 Hash Verification

Purpose: Ensure file integrity during download/transit

How it works:

• Each PDF gets a unique SHA256 hash calculated at build time
• Hash stored in .sha256 files alongside the PDFs
• Combined sha256sum-light.txt for batch verification

Verification command:

sha256sum -c sha256sum-light.txt

2. GPG Signature Verification

Purpose: Verify authenticity and prevent tampering

??? Note "How it works"

- Detached signatures created for each PDF and hash file
- Public keys available in `/pgp/` directory

Verification command:

gpg --import pgp/anonymousplanet-master.asc
gpg --verify export/thgtoa.pdf.sig export/thgtoa.pdf

3. VirusTotal Integration

Purpose: Malware detection and security scanning

??? Note "How it works"

- Automatic scan of all generated PDFs
- Results published in release notes with direct links
- Provides third-party validation of file safety

Usage Examples

Local Development

# Build PDFs locally
python scripts/build_guide_pdf.py --both

# Verify hashes
python scripts/verify_pdf.py --hashes

# Verify signatures (requires GPG installed)
python scripts/verify_pdf.py --signatures

# Full verification with VirusTotal check
export VT_API_KEY=your_api_key
python scripts/verify_pdf.py --all

CI/CD Verification

The workflows automatically verify everything during the build process. To manually trigger:

1. Go to Actions tab
2. Select "Build guide PDF" or "VirusTotal Scan"
3. Click "Run workflow"
4. Download artifacts from successful run

Release Process

When you create a tag (e.g., v1.0.0):

1. Push the tag: git push origin v1.0.0
2. Build PDF workflow triggers automatically
3. VirusTotal scan workflow runs after build completes
4. Both workflows update/create GitHub release with:
   • Light and dark mode PDFs
   • GPG signatures for all files
   • Hash files for verification
   • Release notes with VT scan results

Troubleshooting

Common Issues

GPG signing fails:

• Check that GPG_PRIVATE_KEY is in ASCII armor format
• Verify passphrase is correct
• Ensure key has signing capability

Hash mismatch after download:

• Re-download the file (corruption during transfer)
• Verify you're using the correct hash file
• Check disk integrity

VirusTotal scan fails:

• Verify VT_API_KEY is set correctly
• Check API quota limits (free tier: 4 requests/minute)
• Ensure PDF files exist before scanning

Debug Mode

Enable verbose output by adding to workflow:

- name: Debug
  run: |
    echo "Current directory:" && pwd
    echo "Files in export:" && ls -la export/
    echo "Hash file contents:" && cat sha256sum-light.txt

Best Practices

1. Always verify signatures before opening PDFs from untrusted sources
2. Check VirusTotal results for any suspicious detections
3. Keep GPG keys secure - never commit private keys to repository
4. Monitor API usage for VirusTotal to avoid rate limiting
5. Test locally before pushing tags to production

Future Enhancements

Potential improvements:

• Multi-signature support (multiple maintainers)
• Automated changelog generation with hashes
• Cross-platform signature verification scripts
• Integration with additional malware scanners
• Automatic mirror updates with verified files

---

This workflow is designed for security-conscious users who need to verify the authenticity and integrity of downloaded documents.