DevOps AI Toolkit

# PRD: GitHub Actions CI/CD Pipeline Generation **Created**: 2025-11-18 **Status**: Draft **Owner**: Viktor Farcic **Last Updated**: 2025-11-18 ## Executive Summary Create an MCP prompt that generates GitHub Actions workflows for building, testing, and publishing container images to registries. The prompt guides Claude Code to create CI/CD pipelines that automatically build Docker images from generated Dockerfiles, run tests, apply security best practices, and publish to container registries with appropriate tagging strategies. ## Problem Statement After containerizing applications with Dockerfiles, developers need automated build pipelines but face challenges: ### Current Pain Points - **CI/CD expertise gap**: Setting up GitHub Actions requires understanding workflow syntax, caching, and best practices - **Container registry integration**: Configuring authentication and pushing images is complex - **Image tagging strategy**: Determining appropriate tagging conventions (SHA, semver, latest) is unclear - **Build optimization**: Leveraging caching for faster builds requires deep knowledge - **Security concerns**: Integrating security scanning and best practices is often overlooked - **Manual builds**: Without CI/CD, developers manually build and push images (error-prone, slow) ### Impact - Slow deployment cycles (manual image building) - Inconsistent image tags and versions - Missing security scans in build pipeline - Poor build performance without caching - Increased maintenance burden ## Solution Overview Create `shared-prompts/generate-github-actions.md` that instructs Claude Code to: 1. **Analyze project structure** - Detect Dockerfile, tests, language-specific requirements 2. **Generate workflow file** - Create `.github/workflows/build.yml` with build pipeline 3. **Configure container registry** - Set up GHCR (GitHub Container Registry) authentication 4. **Implement tagging strategy** - Tag images with git SHA and semantic versions 5. **Optimize builds** - Configure Docker layer caching for faster builds 6. **Add security practices** - Include security scanning recommendations ### Key Principles #### Language-Agnostic Design The prompt should provide **workflow patterns** that work across languages: - Pattern: Trigger on push/PR to main branches - Pattern: Build Docker image from Dockerfile - Pattern: Run tests before building (if applicable) - Pattern: Push to container registry with authentication - Pattern: Tag with git SHA and semantic version - Pattern: Use build caching for performance The AI should adapt specifics based on project type. #### Container Registry Strategy **Primary target**: GitHub Container Registry (GHCR) - Built into GitHub (no external service needed) - Free for public repositories - Simple authentication with GITHUB_TOKEN - Good integration with GitHub Actions **Future consideration**: Support for Docker Hub, ECR, GCR, etc. ## User Workflows ### Primary Workflow: Generate CI/CD Pipeline **Prerequisites**: - Project has Dockerfile (generated by PRD #225) - Project is in a GitHub repository **Steps**: 1. User is in project directory with Dockerfile 2. User invokes GitHub Actions generation prompt 3. Claude Code analyzes project: - Verifies Dockerfile exists - Identifies if tests exist and how to run them - Determines appropriate triggers (push/PR) 4. Claude Code generates: - `.github/workflows/build.yml` - Build and publish workflow - Instructions for repository setup (if needed) 5. User commits and pushes workflow file 6. GitHub Actions automatically triggers on next push 7. Image is built and published to GHCR 8. User can deploy image to Kubernetes using recommend tool **Success Criteria**: - ✅ Workflow file is valid GitHub Actions syntax - ✅ Workflow builds Docker image successfully - ✅ Image is pushed to GHCR with correct tags - ✅ Subsequent builds are faster (caching works) - ✅ Workflow is easy to understand and modify ## Technical Design ### Prompt Template Structure **File**: `shared-prompts/generate-github-actions.md` **Input Requirements**: - User is in project directory - Dockerfile exists (from PRD #225) - Project is a GitHub repository **Output Specifications**: - `.github/workflows/build.yml`: Complete CI/CD workflow - Documentation: Setup instructions and usage guide **Prompt Guidance Areas**: #### 1. Project Analysis Guide the AI to: - Verify Dockerfile exists - Detect test commands (npm test, go test, pytest, mvn test, etc.) - Identify build triggers (main branch, tags, PRs) - Determine if multi-platform builds needed (amd64, arm64) #### 2. Workflow Structure Pattern Guide the AI to structure workflow: **Trigger configuration**: - On push to main/master branch - On pull requests to main/master - On version tags (v*.*.*) **Job steps**: 1. Checkout code 2. Set up Docker Buildx (for advanced features) 3. Log in to container registry 4. Extract metadata (tags, labels) 5. Build and push image 6. (Optional) Run tests 7. (Optional) Security scan #### 3. Container Registry Authentication Pattern Guide the AI to configure GHCR authentication: - Use `docker/login-action@v3` - Registry: `ghcr.io` - Username: `${{ github.actor }}` - Password: `${{ secrets.GITHUB_TOKEN }}` #### 4. Image Tagging Strategy Pattern Guide the AI to implement tagging: - **Git SHA tag**: `ghcr.io/owner/repo:abc1234` (specific commit) - **Semantic version**: `ghcr.io/owner/repo:v1.2.3` (on git tags) - **Latest tag**: `ghcr.io/owner/repo:latest` (on main branch) - **Branch tag**: `ghcr.io/owner/repo:branch-name` (feature branches) Use `docker/metadata-action@v5` to automate tagging logic. #### 5. Build Optimization Pattern Guide the AI to optimize builds: - Use `docker/setup-buildx-action@v3` for BuildKit features - Configure cache: `cache-from: type=gha` and `cache-to: type=gha,mode=max` - Enable layer caching for faster subsequent builds #### 6. Security Practices Pattern Guide the AI to include: - Run tests before building (fail fast) - (Optional) Add security scanning step (Trivy, Snyk) - Use pinned action versions (not @latest) - Minimize secrets exposure ## Implementation Milestones ### Milestone 1: Core Workflow Template Created - [ ] `shared-prompts/generate-github-actions.md` created with workflow guidance - [ ] Project analysis guidance documented - [ ] Workflow structure pattern defined - [ ] GHCR authentication pattern documented - [ ] Tagging strategy guidance included ### Milestone 2: Tested with Node.js/TypeScript Project - [ ] Tested with this project (dot-ai) - [ ] Workflow file generated successfully - [ ] Workflow runs without errors on GitHub Actions - [ ] Image built and pushed to GHCR - [ ] Correct tags applied (SHA, latest) - [ ] Build caching working (faster subsequent builds) ### Milestone 3: Tested with Go Project - [ ] Tested with external Go project - [ ] Workflow adapts to Go-specific patterns - [ ] Tests run correctly in workflow - [ ] Image published successfully - [ ] Verifies pattern generalizes across languages ### Milestone 4: Documentation Complete - [ ] `docs/mcp-guide.md` updated with CI/CD pipeline generation guide - [ ] Repository setup instructions documented (GHCR permissions, etc.) - [ ] Troubleshooting guidance provided - [ ] README.md updated with CI/CD capabilities ## Success Criteria ### Functional Requirements - ✅ Generated workflow files are valid GitHub Actions syntax - ✅ Workflows build Docker images successfully - ✅ Images are pushed to GHCR with correct authentication - ✅ Tagging strategy works correctly (SHA, semver, latest) - ✅ Build caching reduces build times on subsequent runs ### Quality Requirements - ✅ Workflow files follow GitHub Actions best practices - ✅ Generated files are human-readable and maintainable - ✅ Prompt works consistently across different languages (validated via Node.js and Go testing) ### Integration Requirements - ✅ Consumes Dockerfile from PRD #225 - ✅ Published images work with recommend tool for deployment - ✅ Published images work with local K8s development (PRD - separate) - ✅ Works seamlessly in Claude Code workflow ### Performance Requirements - ✅ Workflow generation completes in < 30 seconds - ✅ Initial builds complete in reasonable time (< 10 minutes) - ✅ Cached builds are significantly faster (< 2 minutes) ## Risks & Mitigation ### Risk: GHCR Permissions Issues **Impact**: High - Workflow fails to push images **Probability**: Medium (first-time setup) **Mitigation**: - Provide clear documentation for GHCR setup - Include permission troubleshooting guide - Generate workflow with proper authentication from the start - Guide user through repository settings if needed ### Risk: Workflow Syntax Errors **Impact**: High - Workflow doesn't run **Probability**: Low (if tested properly) **Mitigation**: - Test prompt with real projects (Node.js + Go) - Use proven GitHub Actions patterns - Include validation guidance in prompt ### Risk: Build Failures in CI **Impact**: Medium - Workflow runs but build fails **Probability**: Medium (depends on Dockerfile quality) **Mitigation**: - Ensure Dockerfile from PRD #225 is tested locally first - Include test steps that fail fast - Provide build troubleshooting guidance ### Risk: Slow Builds Without Caching **Impact**: Medium - Long build times frustrate developers **Probability**: Low (with proper cache configuration) **Mitigation**: - Emphasize caching patterns in prompt - Use GitHub Actions cache (type=gha) - Test and validate build times in milestones ### Risk: Security Vulnerabilities in Images **Impact**: High - Insecure images deployed to production **Probability**: Medium (without scanning) **Mitigation**: - Include security scanning recommendations in prompt - Consider integrating Trivy or similar tools - Document security best practices ## Dependencies ### Prerequisites - Project has Dockerfile (PRD #225) - Project is in a GitHub repository - User has GitHub account with appropriate permissions ### External Dependencies - GitHub Actions (free for public repos, included in private repo plans) - GitHub Container Registry (GHCR) - Docker Buildx ### Integration Dependencies - PRD #225 (Dockerfile Generation) provides Dockerfile to build - Recommend tool consumes published images for K8s deployment - Future local K8s PRD will use published images for local dev ### Enables - **PRD #202 (GitOps Integration)**: This PRD is a prerequisite for #202. GitOps workflows require CI to update image tags in Helm values.yaml or Kustomize overlays and push to Git. Without automated CI/CD, users would manually update tags, defeating GitOps automation. ## Future Enhancements ### Potential Phase 2 Features - Multi-platform builds (amd64 + arm64) - Integrated security scanning (Trivy, Snyk, Anchore) - Support for additional registries (Docker Hub, ECR, GCR, ACR) - Build matrix for multiple versions/configurations - Automated release workflows with changelogs - Integration with semantic versioning tools - **GitOps manifest updates**: Update image tags in Helm values.yaml or Kustomize overlays and push to GitOps repo (ties into #202) ## Work Log ### 2025-11-18: PRD Creation **Completed Work**: - Created PRD #226 for GitHub Actions CI/CD Pipeline Generation - Defined language-agnostic workflow generation approach - Focused on GHCR as primary container registry - Documented tagging strategy patterns (SHA, semver, latest) - Included build optimization with caching - Simplified to 4 major milestones - Testing scope: Node.js/TypeScript (this project) + Go project **Design Decisions**: - GHCR as primary target (simplest GitHub integration) - Language-agnostic workflow patterns (not language-specific templates) - Build caching using GitHub Actions cache - Security scanning as optional/future enhancement - Focus on core build and publish workflow first **Next Steps**: - Update PRD #22 to reflect focused analysis scope - Begin implementation after PRD #225 (Dockerfile generation) is complete