CI/CD Setup

Complete CI/CD pipeline setup documentation for HTTP File Runner using GitHub Actions.

Overview

This document describes the complete CI/CD pipeline setup for the HTTP File Runner project using GitHub Actions. The pipeline provides automated building, testing, security scanning, and deployment across multiple platforms.

Pipeline Components

The CI/CD pipeline consists of multiple jobs that run in parallel and sequence to ensure comprehensive testing and deployment.

Job Overview

🧪 Test Job

Builds and tests on multiple platforms (Ubuntu, Windows, macOS) using Zig's built-in testing framework.

🔍 CodeQL Analysis

GitHub's semantic code analysis engine for finding security vulnerabilities and coding errors.

🔐 Trivy Vulnerability Scan

Comprehensive vulnerability scanner for containers, filesystems, and Git repositories.

📦 Binary Release

Cross-platform binary compilation and GitHub Release creation with automated asset upload.

🐳 Docker Build & Push

Container image building for multiple architectures and publishing to registries.

📦 Snap Package

Linux universal package building and publishing to Snap Store.

Workflow Triggers

  • Push to main: Full pipeline execution
  • Pull requests: Testing and security scans only
  • Release tags: Complete build, test, and deployment
  • Manual trigger: On-demand workflow execution

Development Tools

Essential tools and automation for development workflow enhancement.

Automated Setup

🛠️ Development Setup Script

PowerShell script that automates the complete development environment setup.

  • Zig compiler installation via Scoop
  • Git hooks configuration
  • Development dependencies
  • IDE extensions (optional)

📋 Issue Templates

Standardized GitHub issue templates for consistent reporting.

  • Bug reports with reproduction steps
  • Feature requests with use cases
  • Documentation improvements
  • Performance issues

🔄 Pull Request Template

Comprehensive PR template ensuring quality submissions.

  • Change description checklist
  • Testing verification
  • Documentation updates
  • Breaking change notifications

Repository Configuration

Essential repository settings and protections for maintaining code quality.

Branch Protection Rules

  • Require pull request reviews before merging
  • Require status checks to pass before merging
  • Require branches to be up to date before merging
  • Require conversation resolution before merging
  • Restrict pushes that create files larger than 100MB

Security: The main branch is protected and requires all checks to pass before merging.

Usage Workflows

Common development workflows and their corresponding CI/CD pipeline behaviors.

Development Workflow

  1. Feature Development: Create feature branch → Implement → Push → CI runs tests
  2. Pull Request: Open PR → CI runs full test suite → Review → Merge
  3. Release: Tag release → CI builds binaries → Creates GitHub release → Publishes packages

CI/CD Behavior by Event

  • Feature branches: Test job only
  • Pull requests: Test + CodeQL + Trivy scan
  • Main branch: Full pipeline without publishing
  • Release tags: Complete pipeline with publishing

Tip: Use conventional commits to trigger automatic versioning and changelog generation.

Pipeline Benefits

Key advantages of this comprehensive CI/CD setup.

🚀

Automated Quality

Comprehensive testing and security scanning on every change

🔒

Security First

Multiple security tools detect vulnerabilities early in development

📦

Multi-Platform

Automated builds for Windows, macOS, Linux, and containers

⚡

Fast Feedback

Parallel job execution provides quick results on all changes

🔄

Reproducible

Consistent build environment ensures reliable deployments

📊

Visibility

Clear status indicators and detailed logs for troubleshooting

Troubleshooting

Common issues and their solutions when working with the CI/CD pipeline.

Common Issues

Build Failures

Compilation errors or test failures in the pipeline.

Solution: Check Zig version compatibility and run tests locally first

Security Scan Failures

Trivy or CodeQL detecting potential vulnerabilities.

Solution: Review findings, update dependencies, or add suppressions if false positive

Docker Build Issues

Container image building failing due to platform differences.

Solution: Test Docker build locally and check multi-arch compatibility

Release Publishing Failures

GitHub release creation or package publishing errors.

Solution: Verify repository permissions and check token scopes

Getting Help

  • Check existing issues and documentation
  • Create issue with appropriate template
  • Review CI logs for detailed error information
  • Use development setup script for local testing

Note: This CI/CD pipeline provides a robust foundation for developing, testing, and releasing the HTTP File Runner project while maintaining high code quality and security standards.