github-actions-guide.md

🚀 GitHub Actions Guide

Comprehensive guide to Discogsography's CI/CD workflows and automation

📋 Workflows | 🔧 Composite Actions | ⚡ Performance | 🛡️ Security | 🎯 Best Practices

📋 Workflows

Discogsography uses GitHub Actions for continuous integration, testing, and deployment automation. All workflows follow consistent patterns with emojis for visual clarity and optimal performance through parallelization and caching.

🏗️ Build Workflow (build.yml)

Trigger: Push to main, PRs, two scheduled crons, manual dispatch Purpose: Main CI pipeline that orchestrates all quality checks and Docker builds

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 1 * * 6"  # Saturday 01:00 UTC — full build
    - cron: "0 4 * * 1"  # Monday 04:00 UTC — security-focused build
  workflow_dispatch:

Jobs:

1. Detect Changes 🔍 - Determines which files changed for conditional execution
2. List Sub-Projects 📋 - Provides service matrix for downstream jobs
3. Code Quality ✅ - Runs linting and formatting checks
4. Security 🛡️ - Comprehensive security scanning
5. Docker Compose Validate 🐳 - Validates docker-compose syntax
6. Docker Validate 🐳 - Dockerfile linting and build testing
7. Tests 🧪 - Executes unit and integration tests (parallel with E2E)
8. E2E Tests 🎭 - Browser-based testing (parallel with unit tests)
9. Aggregate Results 📊 - Collects and summarizes job outcomes
10. Docker Build 🐳 - Builds and pushes images to GitHub Container Registry

Key Features:

• ⚡ Parallel test execution for faster feedback
• 💾 Advanced Docker layer caching
• 📊 Build metrics and performance tracking
• 📢 Discord notifications with build status

🧹 Code Quality Workflow (code-quality.yml)

Trigger: Called by build.yml via workflow_call Purpose: Ensures code quality standards are met

Checks:

• 🎨 Ruff - Fast Python linting and formatting
• 🔍 mypy - Static type checking
• 🛡️ Bandit - Security vulnerability scanning
• 🐳 Hadolint - Dockerfile best practices
• ✅ Pre-commit hooks - All configured checks

🧪 Test Workflow (test.yml)

Trigger: Called by build.yml via workflow_call Purpose: Runs comprehensive test suite

Features:

• 🎯 Smart test detection - skips if no relevant changes
• 📊 Coverage reporting with pytest-cov
• 💾 Test result caching
• 🔄 Grouped test execution to avoid async conflicts

🎭 E2E Test Workflow (e2e-test.yml)

Trigger: Called by build.yml via workflow_call Purpose: Cross-browser end-to-end testing

Test Matrix:

• 🌐 Browsers: Chromium, Firefox, WebKit
• 📱 Devices: iPhone 15, iPad Pro 11
• 🖥️ Platforms: Ubuntu, macOS

Features:

• 🎥 Video recording on failures
• 📸 Screenshot artifacts
• ⚡ Concurrent test limiting (max 3)
• 💾 Browser caching for faster runs

🔄 Update Dependencies (update-dependencies.yml)

Trigger: Weekly schedule (Monday 9 AM UTC) or manual Purpose: Automated dependency updates with PR creation

Options:

• 🐍 Python version updates
• 📦 Major version upgrades
• 🔒 Security patch application

Process:

1. Runs update script
2. Creates PR with detailed summary
3. Assigns reviewers
4. Sends Discord notification

🛡️ Security Workflow (security.yml)

Trigger: Called by build.yml, weekly schedule (Monday 04:00 UTC) Purpose: Comprehensive security scanning across Python, Rust, secrets, and containers

Jobs:

1. Python Security 🐍 — pip-audit (dependency vulnerabilities), bandit (SAST), osv-scanner (multi-ecosystem)
2. Semgrep CE Scan 🔬 — Static analysis with SARIF upload to GitHub Advanced Security; suppressed findings (# nosemgrep) are stripped before upload
3. Rust Security 🦀 — cargo-audit (advisory database), cargo-deny (license and policy checks)
4. Secret Scanning 🔑 — TruffleHog on full history (fetch-depth: 0), verified secrets only
5. Container Scanning 🐳 — Trivy filesystem scan for HIGH/CRITICAL CVEs, SARIF uploaded to GitHub Security tab

Key Features:

• 🔒 Minimal permissions (contents: read, security-events: write)
• 📤 SARIF results uploaded to GitHub Advanced Security for all scanners
• 🚫 Semgrep job skipped for Dependabot PRs (github.actor != 'dependabot[bot]')

🧹 Cleanup Workflows

Cache Cleanup (cleanup-cache.yml)

• Trigger: PR closure
• Purpose: Removes PR-specific caches

Docker Image Cleanup (cleanup-images.yml)

• Trigger: Monthly schedule, manual dispatch (workflow_dispatch)
• Purpose: Removes old Docker images
• Retention: Keeps 2 most recent tagged versions

🐳 Docker Validation (docker-validate.yml)

Trigger: Called by build.yml via workflow_call Purpose: Validates Dockerfiles

Checks:

• 🔍 Dockerfile linting with Hadolint
• 🏗️ Builder-stage Docker build test for all services

🤖 Claude Code (claude.yml)

Trigger: issue_comment (when mentioning @claude) Purpose: Enables AI-assisted development on issues and PRs

Features:

• 💬 Responds to @claude mentions in issue and PR comments
• 🤖 Provides AI assistance for code questions and tasks

🔍 Claude Code Review (claude-code-review.yml)

Trigger: pull_request (open, synchronize, reopened) Purpose: Automated AI code review on pull requests

Features:

• 📝 Performs automated code review on new and updated PRs
• 🔍 Analyzes code changes for quality, bugs, and best practices

🐳 Docker Compose Validation (docker-compose-validate.yml)

Trigger: Called by build.yml via workflow_call Purpose: Validates docker-compose syntax

Checks:

• 📋 docker-compose configuration syntax validation

📋 List Sub-Projects (list-sub-projects.yml)

Trigger: Called by other workflows Purpose: Provides service matrix for build jobs

Output: JSON matrix of services with cache settings

🔧 Composite Actions

Reusable actions that reduce duplication and improve maintainability:

📦 setup-python-uv

Sets up Python environment with UV package manager and caching.

- uses: ./.github/actions/setup-python-uv
  with:
    python-version: "3.13"
    cache-dependency-glob: "**/uv.lock"

Features:

• 🐍 Python setup with specified version
• 📦 UV package manager installation
• 💾 Intelligent dependency caching
• ⚡ Cache restoration with fallbacks

🐳 docker-build-cache

Advanced Docker layer caching for faster builds.

- uses: ./.github/actions/docker-build-cache
  with:
    service-name: dashboard
    dockerfile-path: dashboard/Dockerfile
    use-cache: true

Features:

• 💾 BuildKit cache optimization
• 🔄 Cache hit detection
• 📊 Performance metrics
• 🎯 Service-specific caching

⚡ Performance Optimizations

🚀 Parallelization

• Tests and E2E tests run in parallel after code quality
• Independent Docker builds use matrix strategy
• Concurrent browser tests limited to prevent resource exhaustion

💾 Caching Strategy

• Hierarchical cache keys with multiple fallback levels
• Docker BuildKit inline caching and cache namespaces
• Dependency caching for Python, UV, and pre-commit
• Test result caching for faster subsequent runs

🎯 Conditional Execution

• Skip tests when no relevant files changed in PRs
• Smart file change detection for targeted workflows
• Resource-aware execution based on context

📊 Monitoring & Metrics

• Build duration tracking
• Cache hit rate reporting
• Performance notices in workflow logs
• Enhanced Discord notifications with metrics

🛡️ Security Features

🔒 Least Privilege Permissions

All workflows specify minimal required permissions:

permissions:
  contents: read        # Most workflows
  packages: write      # For Docker push
  pull-requests: write # For PR creation

📌 Action Pinning

• Non-GitHub/Docker actions pinned to specific SHA
• Regular updates through dependabot
• Version comments for clarity

🐳 Container Security

• Non-root user execution (1000:1000)
• No-new-privileges security option
• Trivy container and filesystem scanning for HIGH/CRITICAL CVEs
• Anchore security scanning for images
• Hadolint validation for Dockerfiles

🎯 Best Practices

📝 Naming Conventions

• Steps: Start with emoji for visual scanning
• Jobs: Descriptive names with purpose
• Workflows: Clear, action-oriented names

🎨 Quote Standardization

• Expressions: Single quotes (${{ }})
• YAML strings: Double quotes when needed
• Simple values: Unquoted when appropriate

📢 Notifications

• Discord webhooks for build status
• Detailed error messages in logs
• PR comments for dependency updates
• Workflow status badges in README

🔧 Maintenance

• Weekly dependency updates
• Monthly Docker image cleanup
• Automated cache management
• Regular security scanning

📊 Workflow Status

Monitor workflow health through status badges:

• 
• 
• 
• 

🚀 Getting Started

Running Workflows Locally

Use act to test workflows locally:

# Run specific workflow
act -W .github/workflows/test.yml

# Run with specific event
act pull_request -W .github/workflows/build.yml

# List available workflows
act -l

Debugging Workflows

1. Enable debug logging:

   env:
     ACTIONS_RUNNER_DEBUG: true
     ACTIONS_STEP_DEBUG: true

2. Add debugging steps:

   - name: 🐛 Debug context
     run: |
       echo "Event: ${{ github.event_name }}"
       echo "Ref: ${{ github.ref }}"
       echo "SHA: ${{ github.sha }}"

3. Check workflow runs: Navigate to Actions tab in GitHub

📚 Resources

• GitHub Actions Documentation
• Workflow Syntax Reference
• Composite Actions Guide
• Security Hardening