Cách Sử Dụng GitHub | AI Team Handbook

GitHub là nơi code của mình sống. Không chỉ lưu trữ -- nó là cách mình cộng tác, review code, theo dõi công việc, và tự động hoá deployment.

Ý tưởng lõi: GitHub là "nhà" của dự án. Code, thảo luận, issues, và automation đều nằm ở đây.

GitHub vs Git

Git	GitHub
Chạy trên máy mình	Website/dịch vụ cloud
Theo dõi thay đổi	Lưu trữ repositories
Hoạt động offline	Cần internet
Công cụ command-line	Giao diện web

Dễ nhớ: Git = công cụ, GitHub = nền tảng.

Open Source

Open source nghĩa là source code công khai. Ai cũng có thể xem code, fork, đề xuất thay đổi, dùng cho dự án riêng (theo license).

Nhiều tool mình dùng là open source: NextJS, Supabase, Tailwind, Shadcn UI.

Tại sao quan trọng với mình:

Học được cách người khác build sản phẩm
Report bugs và nhận fixes
Đóng góp lại cho cộng đồng
Dựa vào community duy trì và phát triển

Pull Requests (PRs)

Pull Request là đề xuất merge thay đổi từ branch này sang branch khác. Đây là cơ chế chính để cộng tác trong team.

Vì sao dùng PRs:

Code review -- teammates review trước khi merge
Thảo luận -- comment trên từng dòng code cụ thể
CI/CD -- tests tự động chạy trước khi merge
Lịch sử -- ghi lại thay đổi gì và vì sao

Quy trình

1. Tạo branch → 2. Viết code → 3. Push → 4. Mở PR → 5. Review → 6. Merge

Viết mô tả PR tốt

## What
Thêm authentication với better-auth

## Why
Users cần đăng nhập để lưu keyword clusters

## How
- Thêm better-auth configuration
- Tạo login/signup pages
- Bảo vệ dashboard routes

## Testing
- [x] Đăng ký bằng email được
- [x] Đăng nhập được
- [x] Routes được bảo vệ redirect về login

GitHub Issues

Issues dùng để theo dõi bugs, features, và tasks.

Label	Mục đích
`bug`	Cái gì đó không hoạt động
`feature`	Yêu cầu tính năng mới
`enhancement`	Cải thiện tính năng có sẵn
`documentation`	Docs cần cập nhật

Viết issue tốt

## Mô tả
Keyword export lỗi khi có hơn 1000 keywords.

## Các bước tái hiện
1. Upload CSV với 1500 keywords
2. Chạy clustering
3. Click "Export Results"

## Kỳ vọng
File CSV tải xuống với đầy đủ keywords

## Thực tế
Lỗi: "Request too large" trong console

## Môi trường
- Browser: Chrome 120
- Ngày: 2024-01-15

GitHub Actions (CI/CD)

CI/CD = Continuous Integration / Continuous Deployment.

CI: Tự động test code khi push
CD: Tự động deploy khi tests pass

Push lên GitHub → GitHub Actions chạy → Tests pass → Deploy lên Railway
                                      ↓
                                 Tests fail → Bị chặn, cần fix

GitHub Action cơ bản

Actions nằm trong .github/workflows/:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

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

      - name: Cài dependencies
        run: bun install

      - name: Chạy tests
        run: bun test

      - name: Deploy lên Railway
        run: railway up
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

Actions mình hay dùng

Action	Mục đích
Type checking	Bắt lỗi type trước deploy
Linting	Đảm bảo code style
Tests	Kiểm tra chức năng
Deploy	Push lên Railway

Workflow Hàng Ngày

Bắt đầu

# Lấy code mới nhất
git checkout main
git pull

# Tạo feature branch
git checkout -b feature/keyword-export

# Bắt đầu code (với Claude Code)

Trong lúc làm

# Lưu tiến độ thường xuyên
git add .
git commit -m "WIP: export button layout"

# Push để backup
git push -u origin feature/keyword-export

Kết thúc

# Commit cuối
git add .
git commit -m "Complete keyword export feature"
git push

# Mở PR trên GitHub

# Sau khi review và merge, dọn dẹp
git checkout main
git pull
git branch -d feature/keyword-export

Vệ Sinh Branch

Xoá branch sau khi merge
Giữ main luôn deploy được
Đặt tên branch mô tả rõ ràng

Tham Khảo Nhanh

Mình muốn...	Tính năng GitHub
Đề xuất thay đổi	Pull Request
Báo bug	Issue với label `bug`
Yêu cầu tính năng	Issue với label `feature`
Tự động hoá tests	GitHub Actions
Xem trạng thái dự án	GitHub Projects board
Review code	PR review comments

Tài Liệu Tham Khảo

GitHub Docs
GitHub Skills - Học tương tác