Cách tự động triển khai mã nguồn lên VPS bằng GitHub Actions

Khi cập nhật ứng dụng, việc đăng nhập VPS, kéo mã nguồn và khởi động lại dịch vụ bằng tay có thể tốn thời gian, đồng thời dễ bỏ sót thao tác. Với GitHub Actions, bạn có thể tự động chạy kiểm tra và triển khai mã nguồn lên VPS sau mỗi lần đẩy thay đổi lên nhánh chính.

Bài viết này hướng dẫn quy trình GitHub Actions deploy VPS theo cách dễ áp dụng: VPS lưu bản sao repository, GitHub Actions kết nối qua SSH để cập nhật mã nguồn và khởi động lại dịch vụ. Ví dụ sử dụng ứng dụng Node.js chạy bằng systemd; nếu dùng ngôn ngữ hoặc cách vận hành khác, bạn có thể thay các lệnh tương ứng.

1. Quy trình tự động deploy VPS hoạt động như thế nào?

Trong mô hình này, GitHub Actions đóng vai trò chạy các bước tự động sau khi repository có thay đổi. Một quy trình CI/CD VPS cơ bản thường gồm:

1. Nhà phát triển đẩy mã nguồn lên nhánh main.
2. GitHub Actions tải mã nguồn và chạy các bước kiểm tra, chẳng hạn cài thư viện hoặc chạy test.
3. Nếu kiểm tra thành công, workflow kết nối tới VPS bằng SSH.
4. VPS lấy phiên bản mới nhất từ repository, cài thư viện cần thiết và khởi động lại ứng dụng.
5. Workflow kiểm tra dịch vụ đã hoạt động; nếu có lỗi, lần chạy sẽ được đánh dấu thất bại để bạn kiểm tra.

Cách làm này giúp tạo quy trình tự động deploy VPS có thể lặp lại, thay vì phụ thuộc vào các thao tác thủ công. Bạn cũng có thể xem lịch sử từng lần chạy trong GitHub Actions để biết thay đổi nào đã được triển khai và bước nào gặp lỗi.

2. Chuẩn bị VPS và thông tin kết nối

Trước khi viết workflow, hãy chuẩn bị một VPS Linux có thể truy cập qua SSH. Cài đặt Git và môi trường cần thiết cho ứng dụng. Ví dụ với Node.js, máy chủ cần có Node.js, npm và một dịch vụ systemd để quản lý tiến trình ứng dụng.

Tạo thư mục ứng dụng và tài khoản triển khai

Nên sử dụng một tài khoản riêng cho việc triển khai, không dùng tài khoản root để chạy toàn bộ quy trình. Tạo thư mục ứng dụng, ví dụ /var/www/myapp, rồi bảo đảm tài khoản triển khai có quyền đọc, ghi trong thư mục này.

Trên VPS, clone repository vào đúng thư mục. Với repository riêng tư, hãy cấu hình một deploy key chỉ có quyền đọc mã nguồn để VPS có thể lấy cập nhật. Không nên lưu thông tin đăng nhập cá nhân trong script hoặc trong mã nguồn. Nếu repository công khai, VPS có thể lấy mã nguồn mà không cần xác thực riêng.

Tạo khóa SSH cho GitHub Actions

Tạo một cặp khóa SSH dành riêng cho workflow. Khóa công khai được thêm vào ~/.ssh/authorized_keys của tài khoản triển khai trên VPS; khóa riêng được lưu trong GitHub Secrets. Không chia sẻ khóa riêng hoặc đưa khóa vào repository.

Trong phần cài đặt repository, tạo các Actions secrets sau:

• VPS_HOST: địa chỉ IP hoặc tên miền SSH của VPS.
• VPS_USER: tài khoản triển khai trên VPS.
• VPS_SSH_PRIVATE_KEY: nội dung đầy đủ của khóa riêng.
• VPS_KNOWN_HOSTS: dòng host key của VPS đã được xác minh.

Host key giúp workflow xác thực máy chủ đích, hạn chế nguy cơ kết nối nhầm máy. Hãy lấy và xác minh fingerprint qua một kênh tin cậy trước khi lưu giá trị vào secret; không nên tạo known_hosts một cách mù quáng ngay trong mỗi lần chạy.

3. Tạo workflow GitHub Actions để deploy VPS

Trong repository, tạo tệp .github/workflows/deploy.yml. Ví dụ dưới đây dùng Node.js, chạy kiểm tra trước khi kết nối SSH, sau đó yêu cầu VPS cập nhật nhánh main và khởi động lại dịch vụ:

name: Deploy to VPS

on:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: production-deploy
  cancel-in-progress: false

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

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install and test
        run: |
          npm ci
          npm test --if-present

      - name: Deploy over SSH
        env:
          VPS_HOST: ${{ secrets.VPS_HOST }}
          VPS_USER: ${{ secrets.VPS_USER }}
          VPS_SSH_PRIVATE_KEY: ${{ secrets.VPS_SSH_PRIVATE_KEY }}
          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
        run: |
          set -eu
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          printf '%s\n' "$VPS_SSH_PRIVATE_KEY" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          printf '%s\n' "$VPS_KNOWN_HOSTS" > ~/.ssh/known_hosts
          chmod 600 ~/.ssh/known_hosts

          ssh -i ~/.ssh/id_ed25519 \
            -o IdentitiesOnly=yes \
            "$VPS_USER@$VPS_HOST" 'bash -se' <<'REMOTE'
          set -euo pipefail
          cd /var/www/myapp
          git fetch origin main
          git reset --hard origin/main
          npm ci --omit=dev
          sudo systemctl restart myapp
          sudo systemctl is-active --quiet myapp
          REMOTE

Thay 20, /var/www/myapp và myapp bằng phiên bản Node.js, đường dẫn cùng tên service thực tế. Nếu ứng dụng có bước build, hãy bổ sung lệnh build phù hợp. Lưu ý npm ci --omit=dev chỉ phù hợp khi ứng dụng không cần các gói dev để build trên VPS. Một phương án khác là build trong workflow rồi triển khai sản phẩm đã build.

Các lệnh git fetch và git reset --hard đưa thư mục làm việc trên VPS về đúng trạng thái của nhánh main. Vì reset --hard ghi đè thay đổi chưa commit, không chỉnh sửa mã nguồn trực tiếp trong thư mục triển khai. Cũng không lưu tệp cấu hình, dữ liệu người dùng hoặc nội dung tải lên trong thư mục bị thay thế; hãy đặt chúng ở vị trí riêng và bảo đảm lệnh cập nhật không xóa dữ liệu đó.

Lệnh sudo systemctl cần quyền phù hợp. Hãy cấu hình quyền tối thiểu để tài khoản triển khai chỉ được chạy các thao tác cần thiết với service ứng dụng, thay vì cấp quyền quản trị rộng. Tên service phải tồn tại và được cấu hình để chạy đúng ứng dụng.

4. Kiểm tra và chạy thử lần đầu

Commit workflow rồi đẩy thay đổi lên main. Mở tab Actions của repository để theo dõi từng bước. Nếu tất cả bước thành công, kiểm tra ứng dụng trên tên miền hoặc địa chỉ truy cập đã cấu hình. Có thể kiểm tra trạng thái service trực tiếp trên VPS bằng systemctl status myapp.

Nếu workflow thất bại, hãy đọc log để xác định lỗi xảy ra ở bước cài thư viện, SSH, Git hay khởi động dịch vụ. Một số tình huống thường gặp:

• SSH bị từ chối: kiểm tra đúng người dùng, địa chỉ máy chủ, quyền của khóa riêng và khóa công khai trong authorized_keys.
• Lỗi xác minh host: kiểm tra secret VPS_KNOWN_HOSTS, bảo đảm host key thuộc đúng VPS.
• Không lấy được repository: xác nhận VPS có quyền đọc repository; với repository riêng tư, kiểm tra deploy key và cấu hình remote.
• Không tìm thấy thư mục hoặc service: đối chiếu đường dẫn trong workflow và tên service systemd.
• Ứng dụng không khởi động: kiểm tra log service, biến môi trường và các gói cần thiết. Không đưa tệp .env chứa bí mật vào Git; quản lý cấu hình riêng trên VPS.

5. Lưu ý bảo mật và vận hành

Một quy trình CI/CD VPS an toàn cần bảo vệ cả GitHub lẫn máy chủ. Chỉ cấp secret cho repository và môi trường cần thiết; giới hạn quyền SSH của tài khoản triển khai; luân chuyển khóa khi nghi ngờ bị lộ. Không bật chế độ bỏ qua xác minh host key để xử lý lỗi kết nối.

Nên yêu cầu kiểm tra mã nguồn trước khi triển khai lên môi trường thật. Với nhóm nhiều người, có thể dùng GitHub Environments để yêu cầu phê duyệt trước khi job truy cập thông tin production. Tránh chạy nhiều lần deploy đồng thời; cấu hình concurrency trong ví dụ giúp các lần triển khai không chồng lấn.

Lệnh cập nhật trực tiếp có thể khiến ứng dụng gián đoạn ngắn khi khởi động lại. Với hệ thống cần kiểm soát rủi ro cao hơn, hãy cân nhắc triển khai theo từng release riêng, kiểm tra phiên bản mới trước khi chuyển traffic và giữ lại bản trước để có thể quay lui. Dù chọn cách nào, hãy sao lưu dữ liệu và thử quy trình trên môi trường phù hợp trước khi áp dụng rộng rãi.

Kết luận

GitHub Actions giúp tự động kiểm tra mã nguồn và cập nhật ứng dụng trên VPS mỗi khi có thay đổi, đồng thời lưu lại log để theo dõi. Hãy bắt đầu với một workflow đơn giản, kiểm soát quyền SSH và xác minh kỹ các đường dẫn, service trước khi đưa vào sử dụng. Nếu cần môi trường máy chủ để triển khai ứng dụng, bạn có thể tham khảo các gói VPS của VibeVPS và lựa chọn cấu hình phù hợp với nhu cầu.