goplt/docs/content/stories/epic0/0.4-cicd-pipeline.md

Story 0.4: CI/CD Pipeline and Development Tooling

Metadata

• Story ID: 0.4
• Title: CI/CD Pipeline and Development Tooling
• Epic: 0 - Project Setup & Foundation
• Status: Completed
• Priority: High
• Estimated Time: 3-4 hours
• Dependencies: 0.1

Goal

Establish automated testing, linting, and build processes with a developer-friendly Makefile that enables efficient development workflow.

Description

This story sets up the complete CI/CD pipeline using GitHub Actions and provides a comprehensive Makefile with common development commands. The pipeline should run on every push and pull request, ensuring code quality and buildability.

Deliverables

1. GitHub Actions Workflow (.github/workflows/ci.yml)

Complete CI pipeline with:

• Go 1.24 setup
• Go module caching for faster builds
• Linting with golangci-lint or staticcheck
• Unit tests execution
• Test coverage reporting
• Binary build validation
• Code formatting validation (gofmt)
• Artifact uploads for build outputs

2. Comprehensive Makefile

Developer-friendly Makefile with commands:

• make test - Run all tests
• make test-coverage - Run tests with coverage report
• make lint - Run linters
• make fmt - Format code
• make fmt-check - Check code formatting
• make build - Build platform binary
• make clean - Clean build artifacts
• make docker-build - Build Docker image
• make docker-run - Run Docker container
• make generate - Run code generation
• make verify - Verify code (fmt, lint, test)
• make help - Show available commands

3. Linter Configuration

• .golangci.yml or similar linter config
• Configured rules and exclusions
• Reasonable defaults for Go projects

4. Pre-commit Hooks (Optional)

• Git hooks for formatting and linting
• Prevent committing unformatted code

Implementation Steps

1. Create GitHub Actions Workflow

   • Create .github/workflows/ci.yml
   • Set up Go environment
   • Configure module caching
   • Add linting step
   • Add testing step
   • Add build step
   • Add artifact uploads

2. Create Makefile

   • Define common variables (GO, BINARY_NAME, etc.)
   • Add test target
   • Add lint target
   • Add build target
   • Add format targets
   • Add Docker targets
   • Add help target

3. Configure Linter

   • Install golangci-lint or configure staticcheck
   • Create linter configuration file
   • Set up reasonable rules

4. Test CI Pipeline

   • Push changes to trigger CI
   • Verify all steps pass
   • Check artifact uploads

Acceptance Criteria

• CI pipeline runs on every push and PR
• All linting checks pass
• Tests run successfully (even if empty initially)
• Binary builds successfully
• Docker image builds successfully
• Makefile commands work as expected
• CI pipeline fails fast on errors
• Code formatting is validated
• Test coverage is reported
• Artifacts are uploaded correctly

Related ADRs

• ADR-0010: CI/CD Platform

Implementation Notes

• Use Go 1.24 in CI to match project requirements
• Cache Go modules to speed up CI runs
• Use golangci-lint for comprehensive linting
• Set up test coverage threshold (e.g., 80%)
• Make sure CI fails on any error
• Consider adding security scanning (gosec) in future
• Docker builds should use multi-stage builds

Testing

# Test Makefile commands
make test
make lint
make build
make clean

# Test CI locally (using act or similar)
act push

Files to Create/Modify

• .github/workflows/ci.yml - GitHub Actions workflow
• Makefile - Development commands
• .golangci.yml - Linter configuration (optional)
• .git/hooks/pre-commit - Pre-commit hooks (optional)