Kết Nối Biến Môi Trường GitHub Actions Với Cloudflare

Khi triển khai ứng dụng serverless lên Cloudflare (Workers hoặc Pages) thông qua CI/CD, việc quản lý an toàn các biến môi trường (variables) và dữ liệu nhạy cảm (secrets/API tokens) là yếu tố sống còn.

Bài viết này hướng dẫn cách kết nối GitHub Actions environment variables và secrets với Cloudflare một cách chuẩn xác và an toàn nhất.

Luồng Kiến Trúc (Architecture Flow)#

flowchart LR
    subgraph GitHub["GitHub Ecosystem"]
        G_SEC["GitHub Secrets & Vars<br>(CLOUDFLARE_API_TOKEN, DB_PASS, APP_ENV)"]
        G_ACT["GitHub Actions Runner<br>(CI/CD Pipeline)"]
        G_SEC -->|Inject via env / with| G_ACT
    end

    subgraph CF["Cloudflare Platform"]
        WRANGLER["Cloudflare Wrangler / Deploy Action"]
        CF_WORKER["Cloudflare Worker / Pages / Resource"]
        G_ACT -->|Authenticate & Deploy| WRANGLER
        WRANGLER -->|Push Code, Vars & Secrets| CF_WORKER
    end

Bước 1: Lấy Thông Tin Xác Thực Cloudflare#

Dưới đây là cách tìm và tạo 2 thông tin xác thực từ Cloudflare Dashboard:

1. Lấy CLOUDFLARE_ACCOUNT_ID#

Account ID là chuỗi hex 32 ký tự gắn liền với tài khoản Cloudflare của bạn.

Cách A: Từ mục Workers & Pages (Nhanh nhất)
1. Đăng nhập vào Cloudflare Dashboard ↗.
2. Ở thanh bên trái, nhấp vào Compute (Workers & Pages) (hoặc Workers & Pages).
3. Nhìn sang thanh bên phải mục Account details — nhấp để copy Account ID.
Cách B: Từ đường dẫn URL trình duyệt
1. Khi đang ở dashboard, chọn bất kỳ domain hoặc mục nào.
2. Nhìn lên thanh địa chỉ trình duyệt: https://dash.cloudflare.com/<ACCOUNT_ID>/workers-and-pages
3. Chuỗi ký tự ngay sau dash.cloudflare.com/ chính là Account ID của bạn.

2. Tạo CLOUDFLARE_API_TOKEN#

Không nên dùng Global API Key. Hãy tạo một API Token có phạm vi phân quyền tối thiểu (least privilege).

Ở góc trên cùng bên phải dashboard, nhấp vào biểu tượng User Profile -> My Profile.
Chọn mục API Tokens ở menu bên trái.
Nhấp vào nút Create Token.
Chọn dùng mẫu có sẵn hoặc tùy chỉnh:
- Dùng Template: Tìm mẫu Edit Cloudflare Workers và nhấp Use template.
- Tùy chỉnh (Custom Token): Chọn Create Custom Token và cấu hình:
  - Permissions:
    - Account -> Workers Scripts -> Edit
    - Account -> Workers KV Storage -> Edit (nếu có dùng KV)
    - Account -> Pages -> Edit (nếu có deploy Pages)
  - Account Resources: Include -> All accounts (hoặc chọn tài khoản cụ thể).
Cuộn xuống dưới cùng và nhấp Continue to summary -> Create Token.
Sao chép token ngay lập tức (Cloudflare chỉ hiển thị mã này 1 lần duy nhất).

Kiểm tra nhanh qua CLI (Terminal)#

Bạn có thể xác thực token hoạt động chính xác bằng lệnh curl:

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer <YOUR_CLOUDFLARE_API_TOKEN>"

bash

Phản hồi có "status": "active" xác nhận token hợp lệ và sẵn sàng đưa vào GitHub Secrets.

Bước 2: Cấu hình Secrets và Variables trên GitHub#

Truy cập vào Repository Settings > Secrets and variables > Actions và thiết lập:

1. Repository Secrets (Dữ liệu mã hóa / Nhạy cảm)#

CLOUDFLARE_API_TOKEN: Cloudflare API token có quyền Worker:Edit hoặc Pages:Edit.
CLOUDFLARE_ACCOUNT_ID: Account ID của tài khoản Cloudflare.
APP_SECRET_KEY: Khóa bí mật sử dụng trong runtime của ứng dụng (JWT secret, Database password, API Key bên thứ 3).

2. Repository Variables (Dữ liệu thường / Không nhạy cảm)#

ENVIRONMENT: production hoặc staging.
API_BASE_URL: https://api.example.com.

Bước 3: Cấu hình GitHub Actions Workflow#

Tạo file .github/workflows/deploy.yml để truyền variables và secrets trong quá trình deploy:

.github/workflows/deploy.yml

name: Deploy to Cloudflare

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy
        env:
          # Injected into the Wrangler build environment
          ENVIRONMENT: ${{ vars.ENVIRONMENT }}
          API_BASE_URL: ${{ vars.API_BASE_URL }}
          APP_SECRET_KEY: ${{ secrets.APP_SECRET_KEY }}

yaml

Bước 4: Truy cập Biến trong Cloudflare Workers#

Tùy thuộc vào loại biến (plaintext hay encrypted secret), bạn cấu hình qua wrangler.jsonc hoặc nạp trực tiếp qua CLI:

1. Biến Plaintext công khai (`wrangler.jsonc`)#

Các biến không nhạy cảm có thể khai báo trực tiếp trong file cấu hình:

wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01",
  "vars": {
    "ENVIRONMENT": "production",
    "API_BASE_URL": "https://api.example.com"
  }
}

json

2. Runtime Encrypted Secrets (Đẩy tự động qua Wrangler)#

Để đẩy secret trực tiếp từ GitHub Actions lên Cloudflare mà không bao giờ commit vào mã nguồn git:

      - name: Push Secrets to Cloudflare Worker
        run: |
          echo "${{ secrets.APP_SECRET_KEY }}" | npx wrangler secret put APP_SECRET_KEY
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}