Tự động hóa triển khai website tĩnh với GitHub Actions: Từ Code đến Production
Trong quy trình phát triển phần mềm hiện đại, việc tối ưu hóa quy trình tích hợp và phân phối liên tục (CI/CD) là yếu tố sống còn để đảm bảo tính ổn định và tốc độ phát hành sản phẩm. Đối với các dự án website tĩnh (Static Site Generator) như Next.js, Astro, Jekyll hoặc React thuần, giải pháp hiệu quả nhất thường là kết hợp giữa kho mã nguồn mở GitHub và dịch vụ hosting Git Pages, tất cả được tự động hóa qua GitHub Actions. Bài viết này sẽ hướng dẫn chi tiết cách thiết lập một quy trình CI/CD tự động: khi bạn đẩy code lên nhánh chính, hệ thống sẽ tự động kiểm tra lỗi, biên dịch dự án và triển khai ngay lập tức lên không gian trực tuyến mà không cần can thiệp thủ công.
Khái niệm cơ bản và lợi ích của quy trình tự động
Trước khi đi vào thực hành, chúng ta cần hiểu rõ cơ chế hoạt động. GitHub Actions là một công cụ tự động hóa cho phép bạn tạo các quy trình làm việc (workflows) để xây dựng, kiểm thử, đóng gói và triển khai mã nguồn. Trong bối cảnh này, chúng ta sẽ tạo một workflow kích hoạt mỗi khi có sự kiện push vào nhánh main. Workflow này sẽ chạy trên các máy ảo (runner) do GitHub cung cấp, thực hiện các bước cài đặt môi trường, biên dịch code và cuối cùng là đẩy các file đã xây dựng xong lên kho chứa riêng biệt hoặc kích hoạt tính năng GitHub Pages. Lợi ích lớn nhất của việc này là loại bỏ hoàn toàn các thao tác thủ công, giảm thiểu sai sót do con người gây ra và giúp các thành viên trong đội ngũ tập trung vào việc viết code thay vì quản lý quy trình triển khai.
Cấu hình dự án và chuẩn bị môi trường
Bước đầu tiên quan trọng không kém chính là chuẩn bị cấu trúc dự án của bạn. Đảm bảo dự án của bạn đã có sẵn các file cấu hình cần thiết như package.json để quản lý thư viện, hoặc file cấu hình của framework như next.config.js. Điểm mấu chốt ở đây là bạn cần xác định lệnh build cụ thể của dự án. Hầu hết các dự án JavaScript hiện đại đều sử dụng lệnh npm run build hoặc yarn build để tạo ra các file tĩnh nằm trong thư mục đích (output directory). Đối với Next.js, thư mục này thường là .next hoặc out tùy thuộc vào chế độ static export, còn với React thuần qua create-react-app thì thường là thư mục build. Việc xác định chính xác thư mục đầu ra này là chìa khóa để cấu hình bước triển khai sau này.
Thiết lập file Workflow trong GitHub Actions
Để bắt đầu tạo quy trình tự động, bạn cần tạo một thư mục có tên .github ngay trong thư mục gốc của dự án, bên trong đó tạo thêm thư mục workflows. Trong thư mục này, chúng ta sẽ tạo một file có đuôi .yml, ví dụ như deploy.yml. File này sẽ chứa toàn bộ định nghĩa của quy trình làm việc. Cấu trúc của file YAML này bao gồm phần khai báo trigger để xác định khi nào workflow chạy, phần jobs để định nghĩa nhiệm vụ cần thực hiện và các bước (steps) cụ thể bên trong nhiệm vụ đó. Bạn có thể sử dụng trình soạn thảo code như VS Code để viết file này và đảm bảo tuân thủ đúng cú pháp YAML, đặc biệt là khoảng cách (indentation) phải đồng đều.
Chi tiết các bước trong workflow
Khi viết nội dung bên trong file deploy.yml, chúng ta sẽ đi qua các bước logic cụ thể. Đầu tiên là bước Checkout, nơi hệ thống tải mã nguồn từ kho chứa về máy ảo. Tiếp theo là bước Setup Node.js, rất quan trọng để đảm bảo môi trường có phiên bản runtime chính xác như bạn yêu cầu trong dự án, tránh xung đột phiên bản. Sau đó là bước Caching, giúp lưu trữ các thư viện đã cài đặt (node_modules) vào bộ nhớ đệm của GitHub Actions. Lần chạy tiếp theo, hệ thống sẽ lấy từ cache thay vì tải lại từ đầu, giúp rút ngắn thời gian build đáng kể, có thể giảm từ vài phút xuống chỉ còn vài chục giây. Bước cuối cùng và quan trọng nhất là Build và Deploy, nơi thực thi lệnh biên dịch và đẩy thư mục đầu ra lên nhánh được chỉ định cho GitHub Pages.
Ví dụ mã lệnh chi tiết cho file workflow
Dưới đây là một ví dụ hoàn chỉnh về file cấu hình workflow dành cho một dự án sử dụng Next.js với chế độ export tĩnh. Bạn có thể sao chép và tùy chỉnh các giá trị theo dự án của mình. Lưu ý rằng các dòng code bên dưới được đặt trong thẻ dữ liệu chuyên dụng để đảm bảo định dạng chính xác.
name: Deploy to GitHub Pages
on:
push:
branches:
- main
workflow_dispatch:
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build static files
run: npm run build
env:
NEXT_PUBLIC_ENV: production
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./out
publish_branch: gh-pages
Trong đoạn code trên, phần on xác định workflow sẽ chạy khi có push vào nhánh main hoặc được kích hoạt thủ công. Bước Setup Node.js chỉ định phiên bản 18 và bật tính năng cache cho npm. Biến môi trường NEXT_PUBLIC_ENV được truyền vào bước build để thiết lập chế độ production. Quan trọng nhất là bước deploy sử dụng action peaceiris/actions-gh-pages, với tham số publish_dir trỏ vào thư mục ./out (thư mục đầu ra của Next.js static export) và nhánh đích là gh-pages.
Cấu hình GitHub Pages và xử lý secret
Sau khi commit và đẩy file workflow lên GitHub, bạn cần cấu hình phần Pages trong tab Settings của repository. Vào mục Pages, chọn source là Deploy from a branch, và chọn nhánh gh-pages cùng thư mục / (root). Khi đó, GitHub sẽ hiển thị URL của trang web của bạn. Một điểm quan trọng cần lưu ý là action deploy đã sử dụng $\{\{ secrets.GITHUB_TOKEN \}\}, đây là token mặc định do GitHub cung cấp cho mỗi workflow và đã có sẵn quyền hạn cần thiết để ghi vào repository, do đó bạn không cần tạo thêm secret riêng cho tác vụ này. Tuy nhiên, nếu bạn cần triển khai lên các dịch vụ bên thứ ba như Vercel, Netlify hoặc AWS S3, bạn sẽ cần tạo các secret chứa API key tương ứng trong tab Settings > Secrets and variables > Actions và tham chiếu chúng trong file workflow.
Xử lý lỗi thường gặp và lưu ý quan trọng
Khi triển khai quy trình tự động, bạn không thể tránh khỏi các trường hợp lỗi. Một lỗi phổ biến nhất là đường dẫn thư mục đầu ra không chính xác. Nếu file deploy.yml chỉ định publish_dir: ./build nhưng dự án của bạn thực tế xuất file ra ./dist, thì trang web sẽ hiển thị lỗi 404. Hãy kiểm tra kỹ file package.json hoặc tài liệu của framework bạn dùng. Lỗi thứ hai là vấn đề về đường dẫn tĩnh (static assets). Nếu website không hiển thị CSS hoặc ảnh, thường là do cấu trúc đường dẫn trong code không tương thích với hosting GitHub Pages. Bạn cần kiểm tra base path trong config, ví dụ dùng base: '/ten-dua-tong' trong Astro hoặc Jekyll. Một lưu ý khác là về bảo mật: tuyệt đối không commit các file chứa mật khẩu, API key nhạy cảm trực tiếp vào kho code, hãy luôn sử dụng cơ chế Secrets của GitHub Actions hoặc biến môi trường để quản lý thông tin bảo mật.
Khám phá thêm các tính năng nâng cao
Khi đã quen với quy trình cơ bản, bạn có thể mở rộng khả năng của workflow. Bạn có thể thêm các bước kiểm thử tự động (Testing) bằng cách chèn bước run: npm test trước bước Build. Nếu bước test không thành công, toàn bộ quy trình sẽ dừng lại và không tiến hành deploy, giúp đảm bảo chất lượng code trước khi lên production. Bạn cũng có thể cấu hình workflow chỉ chạy khi có người review và approve, hoặc chạy song song nhiều môi trường (staging, production) trên các nhánh khác nhau. Hơn nữa, việc sử dụng các composite actions hoặc reusing workflows có thể giúp bạn đóng gói lại các logic chung thành một module, giảm thiểu việc viết lại code lặp đi lặp lại cho nhiều dự án khác nhau trong cùng một tổ chức.
Kết luận
Việc thiết lập CI/CD với GitHub Actions cho các dự án website tĩnh là một bước tiến lớn trong việc chuyên nghiệp hóa quy trình phát triển phần mềm. Nó mang lại sự tự động hóa cao, tốc độ phản hồi nhanh và giảm thiểu rủi ro cho các bản phát hành. Qua bài hướng dẫn này, bạn đã nắm được cách cấu trúc file workflow, hiểu rõ cơ chế hoạt động của các bước build và deploy, cũng như biết cách xử lý các lỗi cơ bản có thể xảy ra. Hãy bắt đầu áp dụng ngay quy trình này vào dự án của bạn, từ đó giải phóng sức lao động thủ công và tập trung vào việc tạo ra những giá trị tốt nhất cho sản phẩm của mình. Sự kết hợp giữa Git, GitHub Actions và GitHub Pages chính là nền tảng vững chắc cho bất kỳ kỹ sư phần mềm nào muốn làm chủ công nghệ web hiện đại.