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.
Mục lục
Cập nhật 2026
actions/upload-artifact@v4là 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@v4có sẵncache: 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 trxtừ 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-modebiến lock file thành hợp đồng: CI fail nếucsprojđổ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-buildsaudotnet buildtránh build lại lần hai. Nhưng lưu ý:dotnet testtrê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: productioncho 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@v4vàrole-to-assume: arn:aws:iam::...:role/gh-deploy; điều kiện tin cậy đặt trênsubcủ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 testtự 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ỉ
needskhi 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
pathsfilter quá hẹp: sửaDirectory.Packages.propsnhưng workflow không chạy vì nó chỉ lọc**/*.cs.- Chạy
dotnet restoreba lần trong ba job: dùng artifact của output publish thay vì build lại ở job deploy. GITHUB_TOKENvớiwrite-all“cho nhanh”: mọi action bên thứ ba trong job đều thừa hưởng quyền đó.- Deploy bằng
kubectl applytừ 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
environmentcó approval, xác thực bằng OIDC. concurrencybật cho CI, tắt cho deploy production.
Đọc tiếp trong series:



