CleanArchitecture-template/.brain/.agent/skills/custom-skills/CI-CD/GenerateGitHubActions.md

name, description

name	description
GenerateGitHubActions	Guide to generating a CI/CD pipeline automating Build, Test, Docker Build & Deploy using GitHub Actions.

GenerateGitHubActions Skill

When a user requests the creation of CI/CD Pipelines (e.g., GitHub Actions, or its equivalent for GitLab CI / Azure DevOps), you must generate an automation workflow file following standard steps below.

Purpose

• Automate the source code testing (CI) and deployment (CD) process.
• Ensure any code pushed to the main branch always functions correctly and is ready for production.

Configuration Guide (GitHub Actions)

Create a Workflow file for GitHub Actions.

1. File Path and Name

• Path: .github/workflows/ci-cd.yml
• (Or corresponding platform format: .gitlab-ci.yml for GitLab, azure-pipelines.yml for Azure DevOps).

2. Mandatory Configuration Steps in the YAML File

The workflow needs to progress through these main flows (example below is for GitHub Actions):

Phase 1: Build & Test (CI)

• Triggers: Listen for push or pull_request events on the main branch.
• Environment Setup:
  • Checkout source code (e.g., using actions/checkout@v4).
  • Install the .NET SDK matching the project (e.g., actions/setup-dotnet@v4 for .NET 8.0). Note: Enable Nuget cache to speed up the build.
• Run Tests:
  • Execute dotnet restore, dotnet build --no-restore.
  • Most critically: Run dotnet test --no-build --verbosity normal. (Only if Tests go Green (Passed) should subsequent steps proceed).

Phase 2: Docker Build & Push (Start of CD)

• Prerequisite: Only run if the Build & Test Job was successful (needs: build).
• Log into Container Registry:
  • Login to Docker Hub or Azure Container Registry (ACR) using System Secrets (e.g., DOCKER_USERNAME and DOCKER_PASSWORD).
• Build & Push Image:
  • Build the Image from the Dockerfile (ensure it points to the root directory containing the main project so docker build can access the multiple layers of Clean Architecture).
  • Tag the Image (e.g., latest or via Commit SHA/version).
  • Push the Image to the Registry.

Phase 3: Deploy to Server (CD - Webhook / SSH)

• Use the appleboy/ssh-action library (or similar) to SSH into the target Server.
• Instruct the server to pull the latest Image file from the Registry.
• Important: Prioritize using docker compose to deploy (pull and up) if the user's project structure includes a docker-compose.yml file. This helps restart the entire stack (API, DB, Redis, etc.) rather than just running a standalone docker run.

Default Template File (ci-cd.yml)

Below is the template framework you need to base your designs on when generating files for users:

name: CI/CD Pipeline

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '8.0.x'
        cache: true # Enable Nuget cache; subsequent builds will be twice as fast
        cache-dependency-path: '**/packages.lock.json'
    
    - name: Restore dependencies
      run: dotnet restore
      
    - name: Build
      run: dotnet build --no-restore
      
    - name: Test
      run: dotnet test --no-build --verbosity normal

  docker-build-push:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Log in to Docker Hub
      uses: docker/login-action@v3
      with:
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}
        
    - name: Build and push Docker image
      uses: docker/build-push-action@v5
      with:
        context: .
        file: ./Dockerfile
        push: true
        tags: ${{ secrets.DOCKER_USERNAME }}/detailed-project-name-lowercase:latest

  deploy:
    needs: docker-build-push
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - name: Deploy via SSH
      uses: appleboy/ssh-action@master
      with:
        host: ${{ secrets.SERVER_HOST }}
        username: ${{ secrets.SERVER_USER }}
        key: ${{ secrets.SERVER_SSH_KEY }}
        script: |
          cd /path/to/your/project/on/server # Point to the directory containing docker-compose.yml
          docker compose pull # Pull the newest image (based on the compose file)
          docker compose up -d --build # Restart any services with modifications

Reminders for the AI Agent

• When a User asks to generate a pipeline, ensure you ask the User to confirm their Docker Hub account name, Server Credentials, and remind them to fully configure Secrets on GitHub after the file is generated.
• Automatically replace the project name string (detailed-project-name-lowercase in the template) with the true name of the Project / Repository the User is working on. Convert everything to lowercase when naming the Docker Image to prevent Docker formatting errors.
• If the user utilizes docker-compose, prioritize generating the docker compose up -d command over bare docker run commands.