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

name, description

name	description
GenerateGitHubActions	Hướng dẫn tạo CI/CD pipeline tự động hóa Build, Test, Docker Build & Deploy bằng GitHub Actions.

GenerateGitHubActions Skill

Khi user yêu cầu tạo CI/CD Pipelines (ví dụ: GitHub Actions, hoặc tương đương cho GitLab CI / Azure DevOps), bạn cần sinh ra file luồng tự động hóa theo các bước chuẩn sau đây.

Mục đích

• Tự động hóa quá trình kiểm tra mã nguồn (CI) và triển khai (CD).
• Đảm bảo code push lên nhánh main luôn hoạt động đúng đắn và sẵn sàng lên production.

Hướng dẫn sinh cấu hình (GitHub Actions)

Tạo file luồng công việc Workflow cho GitHub Actions.

1. Đường dẫn và tên file

• Đường dẫn: .github/workflows/ci-cd.yml
• (Hoặc theo định dạng của platform tương ứng: .gitlab-ci.yml cho GitLab, azure-pipelines.yml cho Azure DevOps).

2. Các bước cấu hình bắt buộc trong file YAML

Workflow cần trải qua các luồng chính sau (mẫu dưới dây cho GitHub Actions):

Phân đoạn 1: Build & Test (CI)

• Triggers: Lắng nghe sự kiện push hoặc pull_request vào nhánh main.
• Setup môi trường:
  • Checkout mã nguồn (ví dụ dùng actions/checkout@v4).
  • Cài đặt .NET SDK tương ứng với dự án (ví dụ actions/setup-dotnet@v4 cho .NET 8.0). Lưu ý: Bật tính năng cache Nuget để tăng tốc độ build.
• Run Tests:
  • Chạy khối lệnh dotnet restore, dotnet build --no-restore.
  • Quan trọng nhất: Chạy dotnet test --no-build --verbosity normal. (Chỉ khi Test Xanh (Passed) thì các bước sau mới được chạy tiếp).

Phân đoạn 2: Docker Build & Push (Bắt đầu CD)

• Cần điều kiện: Chỉ chạy khi Job Build & Test thành công (needs: build).
• Đăng nhập Container Registry:
  • Login vào Docker Hub hoặc Azure Container Registry (ACR) sử dụng System Secrets (ví dụ DOCKER_USERNAME và DOCKER_PASSWORD).
• Build & Push Image:
  • Build Image từ Dockerfile (chú ý chỉ đường dẫn thư mục gốc nơi chứa dự án chính để docker build có thể truy cập qua các tầng thư mục Clean Architecture).
  • Gắn tag cho Image (ví dụ: latest hoặc theo Commit SHA/phiên bản).
  • Push Image lên Registry.

Phân đoạn 3: Deploy to Server (CD - Webhook / SSH)

• Dùng thư viện appleboy/ssh-action (hoặc tương tự) để SSH vào Server đích.
• Yêu cầu server pull file Image mới nhất từ Registry.
• Quan trọng: Ưu tiên sử dụng docker compose để deploy (pull và up) nếu cấu trúc dự án của user có file docker-compose.yml, giúp khởi động lại toàn bộ stack (API, DB, Redis...) thay vì chỉ chạy docker run độc lập.

Mẫu File Mặc Định (ci-cd.yml)

Dưới đây là khung mẫu bạn cần căn cứ để thiết kế khi sinh file cho user:

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 # Bật cache Nuget, lần sau build nhanh gấp đôi
        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 }}/chi-tiet-ten-project-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 # Trỏ tới thư mục chứa docker-compose.yml
          docker compose pull # Kéo image mới nhất về (dựa theo file compose)
          docker compose up -d --build # Khởi động lại các service có sự thay đổi

Lưu ý cho AI Agent

• Khi User yêu cầu sinh pipeline, hãy yêu cầu User xác nhận về tên tài khoản Docker Hub, Server Credentials và nhắc họ cấu hình đầy đủ Secrets trên GitHub sau khi sinh file.
• Hãy tự động thay thế chuỗi tên project (chi-tiet-ten-project-lowercase trong mẫu) bằng tên thật của Project / Repository mà User đang thao tác. Chuyển tất cả về chữ thường (lowercase) khi đặt tên Docker Image để tránh lỗi định dạng của Docker.
• Nếu user có dùng docker-compose, hãy ưu tiên sinh lệnh docker compose up -d thay vì docker run thuần.