GitHub Actions Secrets Setup & Management Guide

Giới thiệu: Tại sao GitHub Actions Secrets quan trọng?

Nếu bạn đang sử dụng GitHub Actions để automate CI/CD pipeline, chắc chắn bạn cần sử dụng các sensitive credentials như:

• 🔑 API keys từ services bên thứ ba
• 🗝️ Database passwords
• 🎫 OAuth tokens hoặc personal access tokens
• 📱 Deployment credentials
• 💰 Webhook secrets

Nhưng bạn KHÔNG bao giờ được phép hardcode những thứ này vào code hoặc commit vào repository!

GitHub Actions Secrets setup và management là giải pháp an toàn để lưu trữ sensitive data encrypted. Bài viết này hướng dẫn chi tiết cách thực hiện GitHub Actions secrets setup & management theo best practices, từ tạo secret đến rotation strategy.

---

Phần 1: GitHub Actions Secrets Setup - Hướng dẫn Tạo Secret Từng Bước

Bước 1: Truy cập Repository Settings

Repository → Settings → Secrets and variables → Actions

Bước 2: Click "New repository secret"

Bạn sẽ thấy form với 2 fields:

• Name: Tên của secret (ví dụ: API_KEY, DATABASE_PASSWORD)
• Secret: Giá trị của secret (ví dụ: sk-abc123xyz789)

Bước 3: Nhập Secret Name & Value

Name: VIPZONE_ADMIN_TOKEN
Secret: your-actual-token-value-here

⚠️ Lưu ý quan trọng:

• Secret name nên UPPERCASE + underscores (convention)
• Giá trị secret chỉ hiển thị 1 lần khi tạo
• Sau khi save, GitHub sẽ mask giá trị (bạn không thể xem lại)
• Nếu quên giá trị, phải tạo secret mới và update workflows

Bước 4: Verify Secret Được Tạo

Khi secret được tạo, nó sẽ xuất hiện trong danh sách với:

• ✅ Tên secret
• 📅 Ngày tạo / cập nhật
• 🗑️ Nút delete

---

Phần 2: GitHub Actions Secrets Management - Sử Dụng Secret Trong Workflow

Cách Cơ Bản: Env Variables

name: Deploy

on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up environment
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: |
          # Nội dung secret tự động substitute tại đây
          python3 scripts/deploy.py

Giải thích:

• ${{ secrets.API_KEY }} - GitHub substitute giá trị secret vào đây
• Secret value không bao giờ hiển thị trong logs
• Nếu script hoặc error message inadvertently print secret, GitHub tự động mask nó

Cách Nâng Cao: Secret File

Nếu secret là JSON hoặc có structure phức tạp:

- name: Setup credentials file
  env:
    CREDENTIALS_JSON: ${{ secrets.GCP_CREDENTIALS }}
  run: |
    echo "$CREDENTIALS_JSON" > /tmp/credentials.json
    python3 scripts/gcp_deploy.py --credentials /tmp/credentials.json
    # Cleanup
    rm /tmp/credentials.json

Cách Validate Secret Được Load

- name: Verify secrets loaded
  run: |
    # ĐÚNG: Check xem secret có value hay không (return true/false)
    if [ -z "${{ secrets.API_KEY }}" ]; then
      echo "❌ API_KEY not set in GitHub secrets"
      exit 1
    fi
    echo "✅ API_KEY is configured"
    
    # KHÔNG ĐÚNG: NEVER echo secret value
    # echo "Secret: ${{ secrets.API_KEY }}"  ← Nguy hiểm!

---

Phần 3: Repository Secrets vs Environment Secrets

Repository Secrets

• Accessible từ tất cả workflows trong repo
• Dùng cho shared credentials (chung dùng)
• Ví dụ: GitHub token, general API keys

# Accessible everywhere
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Environment Secrets

• Accessible chỉ khi deploying vào specific environment
• Dùng cho environment-specific credentials (prod, staging, dev)
• Ví dụ: production database password, prod API keys

# Setup environment
environment:
  name: production

# Accessible only in production environment
env:
  PROD_DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }}

Bảng So Sánh

Feature	Repository Secret	Environment Secret
Scope	Tất cả workflows	Specific environment
Quản lý	Settings → Secrets	Settings → Environments
Use case	Shared data	Env-specific data
Protection	Không	Có (require approval)

---

Phần 4: GitHub Actions Secrets Management - Security Best Practices

✅ NÊN LÀM

# 1. Use env variables
jobs:
  deploy:
    env:
      API_TOKEN: ${{ secrets.API_TOKEN }}
    steps:
      - run: python3 deploy.py

# 2. Validate secret exists
- name: Check secrets
  run: |
    [ -n "${{ secrets.API_TOKEN }}" ] || exit 1

# 3. Mask sensitive output
- name: Call API
  env:
    TOKEN: ${{ secrets.TOKEN }}
  run: |
    response=$(curl -H "Authorization: Bearer $TOKEN" ...)
    # Don't echo $TOKEN or response with token

# 4. Use secrets only where needed
- name: Deploy
  env:
    DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
  run: deploy.sh  # Only this step has access to DEPLOY_KEY

# 5. Rotate secrets regularly
# Replace old secret with new one, test, then delete old

❌ KHÔNG NÊN LÀM

# ❌ KHÔNG: Hardcode secrets
- run: curl -H "Authorization: Bearer abc123xyz" https://api.example.com

# ❌ KHÔNG: Echo secret to logs
- run: echo "Token: ${{ secrets.TOKEN }}"

# ❌ KHÔNG: Pass secret as command argument
- run: ./deploy.sh --token "${{ secrets.TOKEN }}"  # Token visible in ps aux

# ❌ KHÔNG: Store secret in file và commit
# echo "${{ secrets.KEY }}" > secrets.json
# git add secrets.json  ← NEVER!

# ❌ KHÔNG: Use secret without validation
- run: python3 api.py  # Script crashes if secret missing

---

Phần 5: Troubleshooting - Khi Secret Không Hoạt Động

Tình huống 1: Secret không được tìm thấy

Error: Unrecognized named-value: 'secrets'

Nguyên nhân: Secret chưa được tạo hoặc tên sai

Fix:

# Verify secret name đúng (case-sensitive)
env:
  API_KEY: ${{ secrets.API_KEY }}  # ✅ Đúng
  API_KEY: ${{ secrets.api_key }}  # ❌ Sai (lowercase)

Tình huống 2: Secret value rỗng

Error: Script crash vì API key undefined

Nguyên nhân: Secret được tạo nhưng value trống, hoặc workflow không reference đúng

Fix:

- name: Validate secret
  run: |
    if [ -z "${{ secrets.API_KEY }}" ]; then
      echo "❌ API_KEY secret is empty or not set"
      exit 1
    fi
    echo "✅ Secret is configured"

Tình huống 3: Secret được expose trong logs

Error: Log file chứa full API key value

Nguyên nhân: Script hoặc error message print secret, hoặc secret không được pass qua env variable

Fix:

# ĐÚNG: Pass through env, GitHub auto-masks
env:
  API_KEY: ${{ secrets.API_KEY }}
run: python3 script.py  # Script reads from env var

# SAII: Secret visible in command
run: python3 script.py --api-key "${{ secrets.API_KEY }}"

Tình huống 4: Workflow fail với exit code 1 nhưng không rõ lý do

Error: "Process completed with exit code 1" nhưng không thấy error message

Nguyên nhân: Secret missing, script không handle gracefully

Fix:

# Add validation script
if [ -z "$API_KEY" ]; then
  echo "❌ Missing API_KEY secret"
  echo "   To fix: Add API_KEY to repository settings"
  exit 0  # Return 0 để workflow continue (graceful degradation)
fi

---

Phần 6: GitHub Actions Secrets Setup & Management Checklist

Khi thêm secret mới, hãy sử dụng checklist bên dưới:

Checklist - Khi Add Mới Secret

Sử dụng checklist này mỗi khi bạn add một secret mới:

Pre-Setup

• Xác định secret cần lưu (API key, password, token?)
• Kiểm tra secret size < 48KB
• Decide: Repository secret hay Environment secret?
• Plan cho secret rotation strategy

Setup

• Tạo secret trong GitHub Settings
• Verify tên secret (UPPERCASE, snake_case)
• Verify value được paste đúng
• Test secret 1 lần (không thể xem lại)

Workflow Integration

• Add env: SECRET_NAME: ${{ secrets.SECRET_NAME }} trong workflow
• Test workflow run
• Verify logs được masked (no plain text secret)
• Add validation step để check secret exists

Documentation

• Document secret name trong README hoặc SETUP.md
• Document cách get/rotate secret value
• Document deadline nếu secret có expiration

Production Deployment

• Test trên staging environment trước
• Verify secret works end-to-end
• Monitor logs cho errors hay leaks
• Schedule regular rotation (quarterly recommended)

---

Phần 7: Setup Guide Cho Dự Án Mới

Khi khởi tạo dự án mới với GitHub Actions, tạo .github/SETUP.md:

# GitHub Actions Setup

## Required Secrets

| Secret Name | Description | How to Get |
|-------------|-------------|-----------|
| `API_TOKEN` | API authentication token | Contact API provider |
| `DB_PASSWORD` | Production database password | Contact DBA |
| `DEPLOY_KEY` | SSH key for deployment | Generate via `ssh-keygen` |

## Setup Steps

1. Go to Settings → Secrets and variables → Actions
2. For each secret in table above:
   - Click "New repository secret"
   - Enter Secret Name exactly as shown
   - Paste Secret value
   - Click "Add secret"
3. Verify secrets in workflow logs (check for `***` mask)

## Testing

```bash
# Run workflow to test secrets
git push origin feature-branch
# Check Actions → workflow run → logs
# Verify no plain-text secrets in logs

Rotation Schedule

• API_TOKEN: Rotate monthly
• DB_PASSWORD: Rotate quarterly
• DEPLOY_KEY: Rotate annually

---

## Kết Luận

GitHub Actions Secrets là powerful tool để manage sensitive data an toàn. Mấu chốt:

✅ **Luôn sử dụng secrets** cho API keys, passwords, tokens
✅ **Luôn validate** secrets tồn tại trước khi dùng
✅ **Luôn mask output** để tránh leak
✅ **Rotate regularly** theo security policy
✅ **Document rõ** secret name và cách get/update

Với best practices trên, bạn sẽ tránh được hầu hết security issues liên quan đến credentials trong CI/CD pipeline.

---

## Tham khảo

- [GitHub Actions Secrets Documentation](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
- [GitHub Actions Environment Variables](https://docs.github.com/en/actions/learn-github-actions/environment-variables)
- [Security Hardening for GitHub Actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
- Bài viết liên quan: [Troubleshooting GitHub Actions Build Failures](/posting/github-actions-ci-cd-build-failure-vipzone-token/)
+++