Cài đặt Claude Code và kết nối GitLab self-hosted

SSH vào VPS mới, tay gõ apt update && pip install claude-code xong, mà muốn nó kéo code từ GitLab riêng của mình về, review pull request, rồi tự push lên? Bài này tôi sẽ hướng dẫn bạn cài đặt Claude Code trên VPS Linux và kết nối nó với GitLab self-hosted (hoặc bất kỳ instance GitLab nào bạn tự quản). Quy trình gồm: tạo Personal Access Token, cấu hình SSH key, thêm remote GitLab vào Claude Code, và test workflow thực tế.

Yêu cầu trước khi bắt đầu

• Một VPS chạy Ubuntu 24.04 LTS hoặc Debian 12 (tôi dùng Ubuntu 24.04 cho bài này). Bạn có thể thuê VPS Linux NVMe với toàn quyền root để chạy.
• User sudo non-root đã được tạo (ví dụ deploy). Không chạy dưới root.
• GitLab self-hosted instance đang chạy, truy cập được qua HTTPS. Có quyền Admin hoặc Maintainer trên repository.
• Python 3.10+ và Git đã cài trên VPS: python3 --version && git --version.
• Đã hiểu cơ bản về SSH, Git remote, và token.

Tóm tắt nhanh, những gì bạn sẽ làm

• Cài Claude Code bằng pip trong môi trường ảo Python.
• Tạo GitLab Personal Access Token với scope api và write_repository.
• Cấu hình SSH key từ VPS đến GitLab self-hosted để clone/push code không mật khẩu.
• Thêm GitLab remote vào Claude Code workspace và chạy lệnh AI để review code.
• Xác minh mọi thứ hoạt động với một merge request thử nghiệm.

Bước 1, Cài đặt Claude Code trên VPS

Claude Code là CLI agent của Anthropic, chạy tốt trên Linux. Cài qua pip:

# Tạo thư mục làm việc
mkdir -p ~/claude-workspace && cd ~/claude-workspace

# Tạo và kích hoạt môi trường ảo Python
python3 -m venv venv
source venv/bin/activate

# Cài Claude Code
pip install --upgrade pip
pip install claude-code

Sau khi cài, kiểm tra phiên bản:

claude-code --version

Output mong đợi: claude-code 0.x.x. Nếu báo lỗi command not found, kiểm tra lại PATH hoặc dùng python3 -m claude_code.

Lưu ý quan trọng: Claude Code cần quyền đọc/ghi thư mục hiện tại. Kích hoạt venv mỗi lần bạn mở terminal mới: source ~/claude-workspace/venv/bin/activate.

Verify cài đặt thành công bằng lệnh chạy thử:

echo "Kiểm tra hoạt động" | claude-code stdin

Nếu mọi thứ ổn, bạn sẽ thấy Claude Code phản hồi.

Bước 2, Tạo Personal Access Token trên GitLab

Claude Code cần một token để xác thực với GitLab API khi clone, push, hoặc tạo merge request.

1. Đăng nhập vào GitLab self-hosted instance của bạn.
2. Vào User Settings → Access Tokens (hoặc /-/user_settings/personal_access_tokens).
3. Đặt tên token: claude-code-vps.
4. Chọn ngày hết hạn (tôi thường đặt 1 năm, sau đó gia hạn).
5. Chọn scopes: api (quyền gọi API đầy đủ) và write_repository (quyền push code).
6. Click Create personal access token và copy ngay token hiện ra, GitLab chỉ hiển thị 1 lần.

Giữ token an toàn. Bạn sẽ dùng nó để clone qua HTTPS trong bước sau.

Cảnh báo bảo mật: Không commit token vào file code. Dùng biến môi trường hoặc lưu trong password manager. Tôi khuyên dùng git config --global credential.helper store nhưng chỉ trên máy cá nhân, không phải server chung.

Bước 3, Cấu hình SSH key cho GitLab self-hosted

Để Claude Code có thể push/pull code mượt mà, cần SSH key không mật khẩu.

3.1. Tạo SSH key trên VPS

ssh-keygen -t ed25519 -C "claude-code@vps" -f ~/.ssh/id_ed25519_glab

Không đặt passphrase (để Claude Code chạy tự động không cần nhập mật khẩu). Nếu bạn lo ngại bảo mật, có thể đặt passphrase và dùng ssh-agent để quản lý session.

2. Thêm public key vào GitLab

Copy nội dung public key:

cat ~/.ssh/id_ed25519_glab.pub

Trên GitLab: vào User Settings → SSH Keys → paste key → đặt title VPS-Claude-Code → chọn Usage type là Authentication & Signing → Add key.

3.3. Cấu hình SSH config

Tạo hoặc sửa file ~/.ssh/config, thêm block cho GitLab instance của bạn:

Host gitlab-self
    HostName gitlab.congty.com   # thay bằng hostname GitLab của bạn
    User git
    IdentityFile ~/.ssh/id_ed25519_glab
    Port 22

Thay gitlab.congty.com bằng địa chỉ thật. Đặt Host là alias ngắn, ví dụ gitlab-self để dùng: git clone git@gitlab-self:namespace/repo.git.

3.4. Verify SSH

ssh -T git@gitlab-self

Output mong đợi: Welcome to GitLab, @username!. Nếu lỗi Permission denied (publickey) thì kiểm tra IdentityFile có đúng đường dẫn không, và key đã add trên GitLab chưa.

Mẹo: Chạy với -v để debug: ssh -Tv git@gitlab-self. Thường gặp lỗi sai port (GitLab self-hosted đôi khi dùng port 2222, 443) hoặc thiếu User git.

Bước 4, Clone repository và thêm vào Claude Code

Bây giờ bạn có thể clone repository GitLab về VPS và cho Claude Code làm việc.

4.1. Clone bằng SSH

cd ~/claude-workspace
git clone git@gitlab-self:username/your-repo.git project-code
cd project-code

Nếu bạn chưa có SSH key hoặc muốn dùng HTTPS cho lần clone đầu, dùng lệnh:

git clone https://oauth2:[email protected]/username/your-repo.git project-code
cd project-code

Thay YOUR_TOKEN bằng token tạo ở Bước 2.

4.2. Cấu hình Git remote cho Claude Code

Claude Code cần biết remote nào là chính. Kiểm tra remote hiện tại:

git remote -v

Output mong đợi: origin git@gitlab-self:username/your-repo.git (fetch/push). Nếu chưa có, thêm:

git remote add origin git@gitlab-self:username/your-repo.git

4.3. Khởi tạo Claude Code trong project

cd ~/claude-workspace/project-code
claude-code init

Lệnh này tạo file .claude/config.json (trong thư mục project) với cấu hình mặc định. Kiểm tra nội dung:

cat .claude/config.json

Bạn có thể chỉnh sửa các setting như allowed_commands, disabled_commands để giới hạn quyền của Claude Code. Ví dụ cấm nó chạy rm -rf:

{
  "disabled_commands": ["rm -rf"]
}

Lưu ý quan trọng: Việc cho Claude Code chạy lệnh shell với root có thể nguy hiểm. Hãy luôn chạy dưới user deploy, không phải root, và giới hạn command trong config.

Bước 5, Test workflow: Claude Code review merge request

Sau khi cấu hình xong, thử một tác vụ thực tế: yêu cầu Claude Code review code trong merge request.

claude-code "Review MR !12, project-code"

Câu lệnh này yêu cầu Claude Code truy cập vào merge request hàng đầu2 của repository, đọc diff, và đưa ra nhận xét. Output sẽ bao gồm: tóm tắt thay đổi, gợi ý cải thiện, và nếu có lỗi cú pháp. Nó có thể tự động comment lại trên GitLab nếu được cấu hình.

Thử thêm một lệnh khác, tạo branch và push code mới:

claude-code "Tạo một file README.md mô tả project, commit và push lên branch mới tên feature-docs"

Claude Code sẽ: tạo file, git add, git commit, git push lên GitLab self-hosted. Nếu SSH key và token đã cấu hình đúng, thao tác này thành công mà không cần nhập password.

Xác minh trên GitLab

Mở trình duyệt, vào GitLab self-hosted → repository của bạn → branch feature-docs, file README.md đã xuất hiện. Nếu có Webhook CI/CD, pipeline sẽ tự động chạy.

Thử thêm lệnh xóa remote branch sau khi test xong:

claude-code "Xóa branch feature-docs trên remote"

Bước 6, Cấu hình bổ sung để Claude Code tự động hóa nhiều hơn

Với Claude Code + GitLab self-hosted, bạn có thể mở rộng ra nhiều tác vụ DevOps hơn. Một số ý tưởng:

• Tự động tạo merge request: claude-code "Tạo một MR mới từ nhánh feature-x lên main. Mô tả ngắn gọn thay đổi."
• Tự động sửa lỗi code: cho Claude Code codebase của bạn, hỏi nó "Tìm và sửa lỗi SQL injection trong module user login", nó sẽ tìm file, sửa, commit, push.
• Chạy CI/CD locally: kết hợp Claude Code với Docker để chạy pipeline giống GitLab Runner trên chính VPS đó.
• Review hàng loạt MR: viết script Bash gọi Claude Code qua stdin để review tất cả MR đang pending trong project.

Lưu ý hiệu năng: Claude Code consume tài nguyên CPU/RAM khá nhiều khi xử lý codebase lớn. Một VPS với tối thiểu 2GB RAM và 2 vCPU là khả dụng. Nếu bạn chạy GitLab self-hosted cùng VPS, cần tối thiểu 4GB RAM.

Xử lý lỗi thường gặp

Lỗi 1: claude-code: command not found
Nguyên nhân: chưa kích hoạt venv. Chạy source ~/claude-workspace/venv/bin/activate trước. Hoặc dùng full path: ~/claude-workspace/venv/bin/claude-code.

Lỗi 2: git push báo Permission denied (publickey)
Kiểm tra SSH key đã add trên GitLab chưa, và SSH config có đúng không. Chạy ssh -T git@gitlab-self để kiểm tra. Đảm bảo port đúng (không phải lúc nào GitLab cũng chạy port 22).

Lỗi 3: Token không có quyền push code
Khi clone qua HTTPS, token cần scope write_repository. Vào GitLab Settings → Access Tokens, kiểm tra lại scope của token claude-code-vps.

Lỗi 4: Claude Code bị treo khi xử lý project lớn
Nguyên nhân: VPS thiếu RAM. Kiểm tra với free -h, nếu swap vẫn chưa được bật hoặc RAM gần đầy thì bạn nên nâng cấp VPS. Xem xét dùng VPS Linux NVMe 4GB để có không gian hoạt động tốt hơn.

Câu hỏi thường gặp

Bài viết liên quan

• Hướng dẫn cài PostgreSQL trên VPS Ubuntu 24.04
• Cách cài Docker trên VPS Ubuntu từ A đến Z
• n8n là gì, những ai nên sử dụng n8n