Phần 8 — Best practices, Debug và OIDC hardening

Series GitHub Actions Toàn Tập — 8 phần:

1. Phần 1 — Tổng quan: CI/CD, GitHub Actions và các khái niệm cốt lõi

2. Phần 2 — Workflow YAML đầu tiên và Triggers nâng cao

3. Phần 3 — Secrets, Variables và Environment protection

4. Phần 4 — Matrix builds, Caching và Artifacts

5. Phần 5 — Self-hosted Runner: cài đặt, security, auto-scaling

6. Phần 6 — Reusable Workflows và Composite Actions

7. Phần 7 — Pipeline thực tế: Next.js + Docker + VPS deploy

8. Phần 8 — Best practices, Debug và OIDC hardening ← bạn đang đọc

Mở đầu

Phần cuối series — gộp ba chủ đề bắt buộc cho mọi pipeline chạy production: best practices tổng hợp từ kinh nghiệm vận hành (pin version, concurrency, timeouts, permissions), kỹ thuật debug khi workflow lỗi (debug log, tmate, act), và OIDC hardening — kỹ thuật quan trọng nhất để bỏ long-lived cloud credentials (AWS access key, GCP service account JSON) khỏi GitHub secrets.

1. Best practices

Tổng hợp từ kinh nghiệm vận hành nhiều dự án:

• Pin version action: dùng @v4 hoặc commit SHA, không dùng @main — tránh bị supply chain attack.

• Tách CI và CD: workflow CI (test/lint) chạy mọi PR; workflow CD (deploy) chỉ chạy khi merge vào main hoặc tag release.

• Fail fast: đặt step rẻ nhất (lint) trước step đắt nhất (build). Job fail sớm → tiết kiệm phút build.

• Concurrency control: tránh deploy đè lên nhau khi 2 PR merge cùng lúc:

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

• Timeouts: luôn đặt timeout-minutes cho job để tránh job treo ăn quota:

jobs:
  build:
    timeout-minutes: 15

• Dùng GITHUB_TOKEN trước khi tạo PAT: token này tự sinh mỗi run, scope hẹp, an toàn hơn personal access token.

• Bật permissions: rõ ràng: theo principle of least privilege:

permissions:
  contents: read
  packages: write  # chỉ khi push GHCR

• Log có cấu trúc: dùng ::group:: để collapse log dài, ::error:: để highlight lỗi trên UI.

• Quản lý phút build: vào Settings → Billing → Actions để xem dashboard. Job dùng nhiều phút nhất thường là build Docker — chuyển sang self-hosted nếu vượt free tier.

2. Debug khi workflow lỗi

Vài kỹ thuật cần biết:

1. Bật debug log: tạo 2 repository secrets ACTIONS_STEP_DEBUG = true và ACTIONS_RUNNER_DEBUG = true rồi re-run workflow — log sẽ verbose hơn nhiều.

2. SSH vào runner đang chạy với action mxschmitt/action-tmate: thêm step - uses: mxschmitt/action-tmate@v3, workflow sẽ in URL SSH để bạn login vào trực tiếp runner. Cực kỳ hữu ích để debug lỗi “máy mình chạy được, CI thì không”.

3. Re-run failed jobs: bấm Re-run failed jobs trong UI để chạy lại đúng job lỗi, không phải chạy lại từ đầu.

4. Act — chạy workflow ở local: cài nektos/act, chạy act push để giả lập event ngay trên máy. Cài đặt 1 lần, debug nhanh hơn nhiều lần.

3. OIDC — bỏ long-lived cloud credentials

Cách cũ để deploy lên AWS/GCP/Azure từ GitHub Actions: lưu access key (hoặc service account JSON) vào repo secret. Vấn đề: key tồn tại vĩnh viễn — lỡ rò rỉ thì kẻ tấn công có quyền cho tới khi bạn rotate. OIDC (OpenID Connect) giải quyết bằng cách cấp token tạm thời cho mỗi workflow run.

3.1. Cách hoạt động

1. Bạn tạo IAM role trên cloud, cho phép trust GitHub OIDC provider (token.actions.githubusercontent.com), giới hạn theo repo/branch/environment.

2. Trong workflow, request OIDC token từ GitHub qua permission id-token: write.

3. Token đó được gửi đến cloud, cloud verify chữ ký GitHub, cấp short-lived credentials (mặc định 1 giờ).

4. Workflow dùng credentials để gọi API cloud — hết hạn tự động, không cần rotate.

3.2. Ví dụ AWS

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
          aws-region: ap-southeast-1
      - run: aws s3 sync ./dist s3://my-bucket

Trust policy phía AWS giới hạn theo repo và branch:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main"
      }
    }
  }]
}

Điều kiện sub giới hạn role chỉ được assume bởi workflow chạy trên branch main của repo cụ thể — kẻ fork repo không thể lợi dụng được.

3.3. Hỗ trợ cloud khác

• GCP: google-github-actions/auth với Workload Identity Federation.

• Azure: azure/login@v2 với Azure AD federated credential.

• HashiCorp Vault: hashicorp/vault-action với JWT auth.

Khi có thể, ưu tiên OIDC over long-lived credentials. Đây là baseline security cho mọi pipeline production năm 2025+.

Tóm tắt

Trong phần này bạn đã nắm:

• Best practices: pin @v4 action, tách CI/CD, fail fast, concurrency.cancel-in-progress, timeout-minutes, permissions: rõ ràng, dùng GITHUB_TOKEN thay PAT.

• Debug: bật ACTIONS_STEP_DEBUG/ACTIONS_RUNNER_DEBUG, SSH vào runner đang chạy qua mxschmitt/action-tmate, chạy workflow local qua nektos/act.

• OIDC: workflow request short-lived token từ GitHub, gửi đến cloud (AWS/GCP/Azure) để assume IAM role — credentials chỉ tồn tại 15 phút - 1 giờ, hết hạn tự động, không cần rotate.

• Bỏ AWS_ACCESS_KEY_ID khỏi secrets: thay bằng aws-actions/configure-aws-credentials@v4 + IAM role trust GitHub OIDC provider, điều kiện sub giới hạn theo repo/branch.

Cảm ơn bạn đã theo dõi 8 phần của series. Bạn đã có đủ công cụ để vận hành pipeline GitHub Actions production-grade. Khi áp dụng vào dự án thật, hãy nhớ: bảo mật trước, tối ưu sau — pin version action, scope permissions hẹp, ưu tiên OIDC over long-lived credentials.

Đây là phần cuối series. Cảm ơn bạn đã theo dõi! Quay lại Phần 1 nếu cần đọc lại từ đầu.