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

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