CI/CD với GitHub Actions cho ứng dụng Docker

GitHub Actions + Docker — Tự động hóa từ code đến container

Khi bạn đã biết viết Dockerfile và dùng Docker Compose, bước tiếp theo là tự động hóa quá trình build và push Docker image mỗi khi code thay đổi. GitHub Actions là công cụ CI/CD miễn phí tích hợp sẵn trong GitHub, rất phù hợp để bắt đầu.

Trong bài viết này, mình sẽ hướng dẫn bạn từ cơ bản đến thực hành: tạo workflow build Docker image, push lên registry, và tối ưu với cache.

I. GitHub Actions là gì?

GitHub Actions là nền tảng CI/CD được tích hợp trực tiếp trong GitHub, cho phép bạn tự động hóa workflow phát triển phần mềm ngay trong repository.

1. Các khái niệm cơ bản

Khái niệm	Giải thích
Workflow	File YAML định nghĩa pipeline, lưu trong `.github/workflows/`
Event	Sự kiện kích hoạt workflow (push, pull_request, tag…)
Job	Một nhóm các bước (steps) chạy trên cùng một runner
Step	Một bước đơn lẻ trong job (chạy lệnh hoặc dùng action)
Action	Thành phần tái sử dụng, có thể do cộng đồng hoặc Docker cung cấp
Runner	Máy ảo thực thi workflow (GitHub cung cấp miễn phí Ubuntu, Windows, macOS)

2. Cấu trúc thư mục

1
2
3
4
5
6
7
my-project/
├── .github/
│   └── workflows/
│       └── docker-build.yml    # Workflow file
├── Dockerfile
├── src/
└── ...

II. Docker Official Actions

Docker cung cấp bộ Actions chính thức giúp bạn build và push image một cách chuẩn hóa:

Action	Chức năng
docker/login-action	Đăng nhập vào Docker registry
docker/setup-buildx-action	Thiết lập Docker Buildx (hỗ trợ build nâng cao)
docker/build-push-action	Build và push Docker image
docker/metadata-action	Tự động tạo tags và labels từ Git metadata
docker/setup-qemu-action	Cài QEMU cho multi-platform build

III. Workflow cơ bản — Build và Push lên Docker Hub

1. Chuẩn bị secrets

Trước khi tạo workflow, bạn cần thêm secrets trong repo GitHub:

Vào Settings → Secrets and variables → Actions
Thêm 2 secrets:
- DOCKERHUB_USERNAME — Tên tài khoản Docker Hub
- DOCKERHUB_TOKEN — Access token (tạo tại hub.docker.com/settings/security)

2. Tạo workflow file

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# .github/workflows/docker-build.yml
name: Build and Push Docker Image

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ secrets.DOCKERHUB_USERNAME }}/myapp:latest

3. Giải thích từng phần

Phần	Ý nghĩa
`on: push: branches: [main]`	Chạy workflow khi push code lên branch `main`
`on: pull_request`	Chạy khi tạo PR (chỉ build, không push)
`actions/checkout@v4`	Clone code từ repo về runner
`docker/login-action@v3`	Đăng nhập Docker Hub bằng secrets
`docker/setup-buildx-action@v3`	Cài Docker Buildx — hỗ trợ cache, multi-platform
`docker/build-push-action@v6`	Build image từ Dockerfile và push lên registry
`push: ${{ github.event_name != 'pull_request' }}`	Chỉ push image khi không phải PR (tránh push image chưa review)

IV. Push lên GitHub Container Registry (GHCR)

Ngoài Docker Hub, bạn có thể push image lên GHCR — registry miễn phí của GitHub, tiện lợi vì không cần tạo tài khoản bên ngoài.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# .github/workflows/docker-ghcr.yml
name: Build and Push to GHCR

on:
  push:
    branches: [main]
    tags: ["v*"]

permissions:
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Điểm khác biệt so với Docker Hub

Tiêu chí	Docker Hub	GHCR
Registry URL	`docker.io` (mặc định)	`ghcr.io`
Authentication	Username + Access Token	`GITHUB_TOKEN` (tự động)
Giá	Miễn phí (giới hạn pull)	Miễn phí (theo quota GitHub)
Tích hợp	Phổ biến nhất	Tích hợp sâu với GitHub

V. Tự động tạo tags với Metadata Action

Thay vì đặt tag thủ công (latest, v1.0), bạn có thể dùng docker/metadata-action để tự động tạo tags dựa trên Git events:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- name: Extract metadata
  id: meta
  uses: docker/metadata-action@v5
  with:
    images: user/myapp
    tags: |
      type=ref,event=branch
      type=ref,event=pr
      type=semver,pattern={{version}}
      type=semver,pattern={{major}}.{{minor}}
      type=sha

Kết quả tags theo từng event

Git Event	Ví dụ	Docker Tag
Push branch `main`	`refs/heads/main`	`main`
Push branch `dev`	`refs/heads/dev`	`dev`
Pull Request #42	`refs/pull/42/merge`	`pr-42`
Push tag `v1.2.3`	`refs/tags/v1.2.3`	`1.2.3`, `1.2`
Commit SHA	`abc1234`	`sha-abc1234`

VI. Tối ưu build với Cache

Mỗi lần workflow chạy, Docker phải build lại từ đầu. Để tăng tốc đáng kể, hãy sử dụng cache.

1. GitHub Actions Cache (Khuyến nghị)

1
2
3
4
5
6
7
8
- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: user/myapp:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

Ưu điểm: Đơn giản nhất, sử dụng GitHub Cache API, không cần cấu hình thêm.

2. Registry Cache

1
2
3
4
5
6
7
8
- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: user/myapp:latest
    cache-from: type=registry,ref=user/myapp:buildcache
    cache-to: type=registry,ref=user/myapp:buildcache,mode=max

Ưu điểm: Cache được lưu trên registry, có thể chia sẻ giữa nhiều CI runners.

So sánh các loại cache

Loại cache	Ưu điểm	Nhược điểm
GitHub Actions (gha)	Đơn giản, không cần setup thêm	Giới hạn 10GB/repo
Registry	Chia sẻ được, persistent	Tốn bandwidth upload
Inline	Gắn liền với image	Chỉ hỗ trợ `min` mode

VII. Ví dụ thực tế — Workflow hoàn chỉnh

Dưới đây là workflow hoàn chỉnh kết hợp tất cả best practices:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# .github/workflows/docker-ci.yml
name: Docker CI/CD

on:
  push:
    branches: [main, dev]
    tags: ["v*.*.*"]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

permissions:
  contents: read
  packages: write

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Luồng hoạt động

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
Developer push code lên GitHub
        ↓
GitHub Actions tự động kích hoạt
        ↓
Checkout code → Setup Buildx → Login Registry
        ↓
Tự động tạo tags từ Git metadata
        ↓
Build Docker image (có cache)
        ↓
Push image lên GHCR (nếu không phải PR)
        ↓
Image sẵn sàng để deploy 🚀

VIII. Troubleshooting phổ biến

1. Lỗi authentication

Lỗi:

1
Error: denied: denied

Nguyên nhân: Secrets chưa được cấu hình hoặc token hết hạn.

Giải pháp:

Kiểm tra secrets trong Settings → Secrets and variables → Actions
Với GHCR: đảm bảo có permissions: packages: write trong workflow
Với Docker Hub: tạo lại Access Token tại hub.docker.com

2. Build chậm

Nguyên nhân: Không sử dụng cache hoặc Dockerfile chưa tối ưu layer.

Giải pháp:

1
2
3
# Thêm cache vào build step
cache-from: type=gha
cache-to: type=gha,mode=max

Và đảm bảo Dockerfile tận dụng layer caching (copy package.json trước, COPY . . sau).

3. Lỗi permission khi push lên GHCR

Lỗi:

1
Error: unexpected status from HEAD request: 403 Forbidden

Giải pháp: Thêm permissions vào workflow:

1
2
3
permissions:
  contents: read
  packages: write

Ghi chú triển khai

Khi áp dụng vào dự án của bạn, hãy lưu ý các điểm quan trọng:
- Luôn dùng secrets cho credentials, không bao giờ hardcode token trong workflow
- Sử dụng push: ${{ github.event_name != 'pull_request' }} để tránh push image từ PR chưa review
- Pin version cho actions (dùng @v3, @v6 thay vì @main)
Best practices:
- Sử dụng docker/metadata-action để quản lý tags tự động
- Bật cache (type=gha) để tăng tốc build
- Tách workflow cho build + test và deploy riêng biệt
Troubleshooting:
- Xem logs chi tiết trong tab Actions của repo GitHub
- Dùng docker compose config để validate cấu hình trước khi push
- Kiểm tra quota cache GitHub tại Settings → Actions → Cache

🎯 Lời kết

GitHub Actions + Docker là combo mạnh mẽ để tự động hóa pipeline từ code đến container image. Với các workflow trong bài viết này, bạn có thể:

✅ Tự động build Docker image mỗi khi push code
✅ Push image lên Docker Hub hoặc GHCR
✅ Tự động tạo tags theo Git metadata (branch, tag, SHA)
✅ Tối ưu tốc độ build với cache

Nếu bạn thấy bài viết này hữu ích, hãy nhớ ⭐ star repo hoặc 📱 chia sẻ với bạn bè nhé! 😊

Tài liệu tham khảo

GitHub Actions Documentation — Tài liệu chính thức GitHub Actions
Docker Build GitHub Actions — Hướng dẫn chính thức Docker cho GitHub Actions
Docker/build-push-action — Repository chính thức của Build and Push Action
Cache management with GitHub Actions — Hướng dẫn cache cho Docker build trên GitHub Actions