GitHub Actions cho ASP.NET Core: Tự động hóa quy trình Build, Test và Deploy (CI/CD)

Pipeline đầu tiên thường mất 10–15 phút vì mỗi job restore lại toàn bộ NuGet, build lại từ đầu, và deploy bằng một PAT hết hạn sau 90 ngày. Bài này dựng pipeline cho ASP.NET Core 10 theo hướng ngược lại: cache đúng chỗ, quyền tối thiểu, OIDC thay secret dài hạn, và tách phần build dùng lại được giữa các repo.

Cập nhật 2026

  • actions/upload-artifact@v4 là bản duy nhất còn chạy; v3 đã bị gỡ. Artifact không chia sẻ được giữa hai job nếu tên trùng — mỗi lần upload phải có tên riêng.
  • actions/setup-dotnet@v4 có sẵn cache: true, nhưng chỉ có tác dụng khi repo có packages.lock.json; không có lock file thì “cache NuGet” là ảo giác.
  • .NET 10 dùng Microsoft.Testing.Platform cho dotnet test ở project MTP (xUnit v3, MSTest 4). Cờ CLI khác VSTest, nên đừng copy --logger trx từ bài cũ mà không kiểm tra.
  • OIDC federated credential thay PAT/service principal secret cho Azure và AWS; đây là thay đổi bảo mật lớn nhất trong 2 năm qua.
  • Image build bằng buildx với cache type=gha, không cần tự dựng registry cache.

Khung workflow và quyền tối thiểu

GITHUB_TOKEN mặc định có quyền rộng. Đặt permissions ở cấp workflow về contents: read, rồi mở từng quyền ở cấp job khi thật sự cần. Một pipeline build không có lý do gì được ghi vào repo.

name: ci

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

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

cancel-in-progress: true đúng cho CI: push mới làm push cũ vô nghĩa. Nhưng nếu workflow này cũng deploy production, hãy tách workflow deploy và đặt cancel-in-progress: false ở đó — huỷ một deploy đang chạy giữa lúc helm upgrade để lại release ở trạng thái nửa vời.

Build, test, publish trên matrix

jobs:
  build-test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        dotnet: ["10.0.x"]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ matrix.dotnet }}
          cache: true
          cache-dependency-path: "**/packages.lock.json"

      - name: Restore
        run: dotnet restore Shop.slnx --locked-mode

      - name: Build
        run: dotnet build Shop.slnx -c Release --no-restore

      - name: Unit tests
        run: dotnet test Shop.slnx -c Release --no-build --filter "Category!=Integration"

      - name: Integration tests (Linux only)
        if: runner.os == 'Linux'
        run: dotnet test Shop.slnx -c Release --no-build --filter "Category=Integration"

      - name: Publish
        if: matrix.os == 'ubuntu-latest'
        run: dotnet publish Shop.Api/Shop.Api.csproj -c Release --no-build -o ./publish

      - uses: actions/upload-artifact@v4
        if: matrix.os == 'ubuntu-latest'
        with:
          name: shop-api-${{ github.sha }}
          path: ./publish
          retention-days: 7

Vài chi tiết quyết định thời gian chạy:

  • --locked-mode biến lock file thành hợp đồng: CI fail nếu csproj đổi dependency mà không cập nhật lock. Đây là thứ khiến cache có nghĩa, vì key cache bám vào nội dung lock file.
  • fail-fast: false để thấy cả lỗi Windows và Linux trong một lần chạy, thay vì sửa từng cái một.
  • --no-build sau dotnet build tránh build lại lần hai. Nhưng lưu ý: dotnet test trên solution sẽ chạy mọi test project; nếu solution lớn, chia job theo project để chạy song song.
  • Artifact chỉ upload từ một nhánh matrix, nếu không hai job ghi cùng tên và job sau fail.

Đừng đưa .NET 11 vào matrix như một bản ổn định: tháng 11/2026 nó vẫn là RC3 (STS). Nếu muốn thử, thêm một job continue-on-error: true và đọc kết quả như tín hiệu, không như gate.

Kết quả test: VSTest và MTP không dùng chung cờ

.NET 10 chạy dotnet test qua Microsoft.Testing.Platform ở project đã bật MTP (xUnit v3, MSTest 4). Với VSTest, xuất kết quả bằng --logger "trx;LogFileName=results.trx"; với MTP, dùng --report-trx từ package Microsoft.Testing.Extensions.TrxReport. Nhầm cờ thì lệnh không lỗi rõ ràng — nó chỉ không tạo file, và job upload artifact “xanh” với thư mục rỗng. Hãy kiểm tra file tồn tại trước khi upload, hoặc để if-no-files-found: error.

Với PR, tải TRX lên rồi render thành check riêng để reviewer thấy test nào fail mà không phải mở log. Đây là thứ đáng làm sớm: nó biến “CI đỏ” từ một thông báo thành một danh sách việc.

Testcontainers trong CI

Testcontainers 4.16 chạy tốt trên ubuntu-latest vì runner có Docker sẵn. Trên windows-latest, Docker chỉ phục vụ Windows container — image Linux như Postgres sẽ không start; trên macOS runner cũng không có Docker Linux. Vì vậy integration test dùng container phải chạy trên Linux, và job Windows chỉ chạy unit test.

Hai cái bẫy hay gặp: pin image test theo tag cụ thể (postgres:17) thay vì latest để kết quả tái lập; và đặt timeout cho container start, vì lần pull đầu trên CI chậm hơn máy local rất nhiều. Nếu nhiều test project cùng dùng một Postgres, dùng một fixture ở cấp collection thay vì start container cho từng test class.

Build và push image lên GHCR

  image:
    needs: build-test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha,prefix=
            type=ref,event=tag

      - uses: docker/build-push-action@v6
        id: build
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

packages: write chỉ ở job này, không ở cấp workflow. GITHUB_TOKEN đủ để push GHCR trong cùng repo — không cần PAT. Tên image lấy từ github.repository phải viết thường; repo có chữ hoa sẽ làm tag không hợp lệ, nên nhiều team hard-code ghcr.io/evotek/shop-api thay vì suy ra.

Tag type=sha cho mỗi commit là thứ CD nên deploy, không phải latest. Với multi-arch, thêm docker/setup-qemu-action@v3 và platforms: linux/amd64,linux/arm64; chỉ làm khi thật sự có node ARM, vì thời gian build tăng gần gấp đôi.

Deploy: environment, approval, OIDC

  deploy:
    needs: image
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://api.example.com
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: Set AKS context
        run: |
          az aks get-credentials \
            --resource-group rg-shop \
            --name aks-shop \
            --overwrite-existing

      - uses: azure/setup-helm@v4
        with:
          version: v3.18.0

      - name: Deploy
        run: |
          helm upgrade --install shop-api ./charts/shop-api \
            --namespace shop --create-namespace \
            -f values.production.yaml \
            --set image.digest=${{ needs.image.outputs.digest }} \
            --atomic --timeout 5m

Ba điều làm cấu hình này an toàn hơn cách cũ:

  • environment: production cho phép gắn required reviewers và giới hạn branch được deploy. Approval xảy ra trước khi job chạm credentials, không phải sau.
  • id-token: write + federated credential: GitHub ký một token ngắn hạn, Azure đổi lấy access token. Không có client secret nào trong repo. Federated credential phải khớp subject — thường là repo:org/repo:environment:production, nên đổi tên environment là phải sửa bên Azure.
  • AWS tương tự với aws-actions/configure-aws-credentials@v4 và role-to-assume: arn:aws:iam::...:role/gh-deploy; điều kiện tin cậy đặt trên sub của token, không chỉ trên repo.

Một chi tiết dễ bỏ: job deploy cần output digest từ job image. Khai báo outputs ở job image trỏ tới steps.meta.outputs.digest, và đảm bảo job image chạy cả trên nhánh main — nếu nó chỉ chạy trên PR, deploy không có gì để tham chiếu.

Reusable workflow thay vì copy-paste

# .github/workflows/reusable-build.yml
on:
  workflow_call:
    inputs:
      dotnet-version:
        type: string
        default: "10.0.x"
    outputs:
      artifact-name:
        value: ${{ jobs.build.outputs.artifact-name }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-name: ${{ steps.upload.outputs.artifact-name }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ inputs.dotnet-version }}
          cache: true
          cache-dependency-path: "**/packages.lock.json"
      - run: dotnet test Shop.slnx -c Release --logger "trx;LogFileName=results.trx"
      - id: upload
        uses: actions/upload-artifact@v4
        with:
          name: results
          path: "**/*.trx"

Caller dùng uses: ./.github/workflows/reusable-build.yml với with:; secret phải khai báo ở workflow_call.secrets hoặc dùng secrets: inherit (chỉ khi caller và callee cùng repo). Reusable workflow giải quyết bài toán “5 repo cùng một pipeline”; composite action giải quyết bài toán “5 step lặp lại trong một job”. Đừng trộn hai khái niệm.

Cache: ba lỗi làm nó vô dụng

  • Cache obj/: file generated chứa đường dẫn tuyệt đối và trạng thái của máy build trước. Kết quả là build lỗi khó hiểu. Chỉ cache ~/.nuget/packages.
  • Key không gắn lock file: dependency đổi nhưng cache hit, build dùng package cũ. Key phải là hash của packages.lock.json.
  • Cache không bao giờ ghi: cache chỉ lưu khi job thành công, và bị evict sau 7 ngày không dùng; repo có giới hạn 10 GB. Nếu cache liên tục miss, kiểm tra nhánh — cache tạo trên feature branch không dùng được ở nhánh khác.

Đo trước khi tối ưu

Mở một lần chạy bất kỳ và đọc thời gian từng step. Ba nguồn chậm phổ biến, theo thứ tự:

  • Restore — nếu chiếm hơn 30% thời gian, vấn đề là cache key hoặc thiếu lock file, không phải runner.
  • Build hai lần — một lần cho app, một lần dotnet test tự build. --no-build ở bước test cắt phần này, nhưng chỉ khi build trước đó dùng cùng cấu hình và cùng output path.
  • Job tuần tự không cần thiết — lint, build, test độc lập có thể chạy song song; chỉ needs khi job sau thật sự tiêu thụ output của job trước.

Đừng tối ưu bằng cách tăng runner trước khi biết thời gian đi đâu. Runner lớn hơn giúp build C# nhanh hơn một chút, nhưng không bù được việc restore lại 200 package ở mỗi job.

Trigger và required checks

Ngoài push và pull_request, hai trigger đáng có: workflow_dispatch với inputs để chạy lại một nhánh cụ thể khi sự cố, và schedule (cron theo UTC) để chạy test hằng đêm trên dependency mới nhất — đây là cách phát hiện lỗi do package ngoài thay đổi mà PR không chạm tới.

Required status checks trong branch protection khớp theo tên job, không theo tên workflow. Đổi tên job từ build-and-test sang build-test làm merge bị chặn dù CI xanh — một lỗi cấu hình tốn cả buổi để tìm. Nếu buộc phải đổi, sửa branch protection trong cùng lần merge.

Cạm bẫy khác

  • paths filter quá hẹp: sửa Directory.Packages.props nhưng workflow không chạy vì nó chỉ lọc **/*.cs.
  • Chạy dotnet restore ba lần trong ba job: dùng artifact của output publish thay vì build lại ở job deploy.
  • GITHUB_TOKEN với write-all “cho nhanh”: mọi action bên thứ ba trong job đều thừa hưởng quyền đó.
  • Deploy bằng kubectl apply từ thư mục manifest không version: không có lịch sử release, rollback thủ công.
Cách xác thực Rủi ro Khi nào dùng
PAT / client secret dài hạn Hết hạn, lộ trong log, không thu hồi được Không còn lý do chính đáng
OIDC federated credential Cấu hình subject sai thì login fail Mặc định cho Azure, AWS, GCP
GITHUB_TOKEN Chỉ trong phạm vi repo GHCR, release, comment PR

Nhìn tới 2027

.NET 11 GA tháng 11/2026 chỉ đổi dotnet-version trong matrix. Phần đáng chú ý là hạ tầng: OIDC thành yêu cầu bắt buộc ở nhiều tổ chức, và các runner lớn hơn (arm64, nhiều core) khiến build đa nền tảng rẻ hơn. Còn lại vẫn là ba câu hỏi cũ: cache có đúng key không, quyền có tối thiểu không, deploy có tái lập được không.

Checklist

  • permissions: contents: read ở cấp workflow, mở từng quyền theo job.
  • Lock file + --locked-mode + cache key theo lock file.
  • Integration test dùng container chỉ trên Linux runner.
  • Image tag theo SHA/digest, không deploy latest.
  • Deploy qua environment có approval, xác thực bằng OIDC.
  • concurrency bật cho CI, tắt cho deploy production.

Đọc tiếp trong series: