---
name: GenerateGitHubActions
description: 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:

```yaml
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.**