GitLab thường được giới thiệu là nền tảng dành cho lập trình viên. Nhưng nhìn ở góc độ quản lý tài sản số, đây còn là một cách tổ chức **tài liệu, mã nguồn và quá trình thay đổi** rất có hệ thống. Người mới có thể bắt đầu bằng một repository lưu bài viết, rồi dần học cách quản lý phiên bản, phân quyền và xuất bản website.

Bài này dùng **GitLab.com (Cloud)** và một blog cá nhân làm ví dụ. Không yêu cầu biết lập trình hay sử dụng Terminal.

## 1. Hiểu năm khái niệm cốt lõi

| Thuật ngữ | Hiểu đơn giản | Ví dụ |
|---|---|---|
| **Namespace** | Không gian sở hữu | Tài khoản cá nhân hoặc Group của tổ chức |
| **Project** | Một dự án với thiết lập và công cụ quản lý | `trung-phan-blog` |
| **Repository** | Kho chứa file và lịch sử thay đổi trong Project | Bài Markdown, hình ảnh, cấu hình |
| **Branch** | Nhánh làm việc độc lập | `main` và `draft/bai-moi` |
| **Commit** | Một mốc lưu thay đổi có ghi chú | “Thêm bài hướng dẫn GitLab” |

**Project không đồng nghĩa với một thư mục.** Project còn có Issues, Merge Requests, thành viên, quyền hạn và có thể có hệ thống tự động hóa CI/CD.

**Git** là công nghệ quản lý phiên bản; **GitLab** là nền tảng giúp sử dụng Git và quản lý cả quy trình làm việc xung quanh nó.

## 2. Tạo Project đầu tiên

1. Đăng nhập [gitlab.com](https://gitlab.com).
2. Chọn **New project → Create blank project**.
3. Đặt tên dễ nhận biết, chẳng hạn `my-first-notes`.
4. Chọn **namespace**: tài khoản cá nhân nếu đây là tài sản cá nhân; Group nếu thuộc tổ chức.
5. Chọn **Private** nếu chưa có lý do công khai mã nguồn.
6. Bật **Initialize repository with a README**, rồi tạo Project.[^projects]

Một file `README.md` mô tả mục đích Project rất hữu ích. Người xem repository sẽ hiểu ngay nó chứa gì và sử dụng ra sao.

### Public, Internal hay Private?

- **Private:** chỉ những người được cấp quyền phù hợp mới truy cập repository.
- **Public:** bất kỳ ai cũng có thể xem phần công khai của Project.
- **Internal:** khả dụng tùy loại triển khai và quyền cấu hình; không nên mặc định coi đây là lựa chọn cho GitLab.com.[^internal]

Chế độ công khai website không nhất thiết giống chế độ công khai repository. Ví dụ, một blog có thể giữ **repository Private** nhưng dùng **GitLab Pages Public** để độc giả đọc website.

## 3. Tạo và sửa file không cần cài phần mềm

Cách dễ nhất là sử dụng **Web Editor**:[^webeditor]

1. Mở Project và vào thư mục cần sửa.
2. Chọn một file rồi chọn **Edit**, hoặc dùng nút **+ → New file**.
3. Chỉnh sửa nội dung, nhập **Commit message** mô tả thay đổi.
4. Chọn commit vào nhánh hiện tại nếu có quyền, hoặc tạo nhánh mới.

Ví dụ, tạo `content/posts/bai-dau-tien.md`. Markdown dùng cú pháp rất đơn giản:

```markdown
---
title: "Bài viết đầu tiên"
---

Đây là đoạn mở đầu.

## Một ý quan trọng

- Luận điểm thứ nhất
- Luận điểm thứ hai
```

Tiêu đề bài đặt ở dòng `title`; trong thân bài, tiêu đề các mục bắt đầu từ `##`.

Với nhiều file một lúc, **Web IDE** thuận tiện hơn. Mở từ **Code → Open in Web IDE**, chỉnh các file ở thanh Explorer, sau đó dùng **Source Control** để commit.[^webide] Khác với việc sửa file ngay trên máy, việc lưu vào GitLab tạo ra lịch sử có thể tra cứu và so sánh.

## 4. Vì sao cần Branch và Merge Request?

Giả sử website đang chạy ổn định trên nhánh `main`, nhưng cần viết lại một bài phân tích lớn. Thay vì sửa trực tiếp `main`, có thể:

1. Tạo branch `draft/cap-nhat-bai-viet`.
2. Chỉnh nội dung và commit nhiều lần trên branch đó.
3. Tạo **Merge Request (MR)** để xem lại toàn bộ thay đổi.
4. Khi đã duyệt, **Merge** vào `main`.

MR là một đề nghị hợp nhất thay đổi; tại đây có thể bình luận, so sánh file và giải quyết từng *discussion thread*.[^mr] Trong tổ chức, đây là công cụ giúp tránh tình trạng “không biết ai sửa, sửa gì, vì sao sửa”.

Với blog một tác giả, dùng nhánh riêng cho những thay đổi lớn là hữu ích nhưng không bắt buộc cho mọi chỉnh sửa nhỏ.

## 5. Những quyền truy cập cần biết

| Vai trò | Công việc điển hình |
|---|---|
| **Guest** | Tham gia trao đổi với quyền hạn hạn chế |
| **Reporter** | Xem và theo dõi thông tin dự án |
| **Developer** | Đóng góp nội dung/mã nguồn trên các nhánh được phép |
| **Maintainer** | Quản trị nhiều thiết lập và quy trình Project |
| **Owner** | Quyền quản lý cao nhất trong phạm vi tương ứng |

Quyền cụ thể còn phụ thuộc cấu hình Project/Group và tính năng GitLab.[^roles] Với blog hoàn toàn cá nhân, mô hình đơn giản là **chỉ chủ sở hữu có quyền ghi**, không mời thêm người vào Project.

Bảo mật tối thiểu nên có:

- Bật **2FA** cho tài khoản.
- Chỉ tạo **Access Token** khi thật sự cần, cấp phạm vi và thời hạn tối thiểu.
- Không đưa mật khẩu, API key hoặc tài liệu bí mật vào repository, kể cả khi repository Private.
- Bảo vệ nhánh `main` và không cho phép force push nếu không có lý do đặc biệt.
- Định kỳ rà soát thành viên và sao lưu dữ liệu ra nơi độc lập.[^members]

**Một lưu ý:** Ai có quyền tải repository về thường có thể giữ bản sao Git của nội dung. Vì vậy, kiểm soát thành viên luôn quan trọng hơn việc chỉ đặt tên Project là “private”.

## 6. GitLab Issues, CI/CD và Pages để làm gì?

**Issues** là các đầu việc: chẳng hạn “viết bài AI”, “kiểm tra link hỏng” hoặc “cải thiện giao diện di động”.

**CI/CD Pipeline** là chuỗi công việc tự động chạy sau khi có thay đổi, ví dụ kiểm tra file, xây dựng website và triển khai. GitLab hiển thị trạng thái như *Running*, *Passed* hoặc *Failed* trong **Build → Pipelines**.

**GitLab Pages** cung cấp nơi xuất bản website tĩnh.[^gpages] Đối với blog dùng **Hugo**, quy trình có thể là:

```text
Bài viết Markdown
       ↓
GitLab Repository
       ↓
CI/CD chạy Hugo
       ↓
HTML/CSS được tạo
       ↓
GitLab Pages xuất bản website
```

Một bài nháp có trường `draft: true` trong Hugo thường được loại khỏi bản build công khai. Khi chủ sở hữu duyệt bài và đặt `draft: false`, pipeline tiếp theo có thể đưa bài đó lên website. Điều này chỉ an toàn khi cấu hình build production không cố tình bao gồm draft.

## 7. Quy trình thực tế cho blog một người

Tôi khuyến nghị một quy trình đơn giản, có thể lặp lại:

1. **Ý tưởng:** Ghi tiêu đề và luận điểm chính.
2. **Soạn:** Viết bài bằng Markdown, có thể nhờ AI hỗ trợ cấu trúc và biên tập.
3. **Kiểm chứng:** Đối chiếu dữ kiện và liên kết nguồn trước khi đăng.
4. **Duyệt:** Chủ blog đọc phiên bản cuối, quyết định xuất bản.
5. **Đăng:** Đặt `draft: false` và commit nội dung.
6. **Kiểm tra:** Xem pipeline **Passed** và mở trang web công khai.
7. **Lưu trữ:** Giữ lịch sử Git, sao lưu repository và các dữ liệu quan trọng.

AI có thể hỗ trợ rất sâu ở bước 2 và 3, nhưng **quyền xuất bản vẫn phải do chủ sở hữu kiểm soát**. Nếu sau này kết nối AI với GitLab bằng token có quyền ghi, cần nhận thức rằng AI khi đó cũng có khả năng thay đổi nội dung; quy trình phê duyệt bằng GitLab phải được thiết kế phù hợp.

## 8. Những lỗi người mới thường gặp

**Mở Settings bị 404:** Kiểm tra đúng tài khoản đang đăng nhập, đúng URL Project và quyền truy cập; thử đi từ trang Project qua menu **Settings** thay vì đường dẫn trực tiếp.

**Tải file lên Web IDE không được:** Thử Web Editor cho từng file, chức năng Upload của repository, hoặc dùng Git trên máy với dự án nhiều thư mục. Không tải cả thư mục cha lồng vào repository nếu công cụ build yêu cầu file cấu hình ở thư mục gốc.

**Đã commit nhưng website chưa đổi:** Xem **Build → Pipelines**. Commit thành công không đồng nghĩa build và deploy thành công.

**Repository Private, người khác không xem được blog:** Kiểm tra **Pages access control**. Đây là quyền đọc website, khác quyền đọc repository.[^pages]

**Thay đổi nhầm file:** Xem **Code → Commits** để biết thay đổi gần đây. Git cung cấp khả năng so sánh và đảo ngược thay đổi, nhưng cần cân nhắc kỹ trước khi thực hiện trên nhánh chính.

## Kết luận

GitLab không chỉ là nơi “cất code”. Nó là một phương pháp quản trị thay đổi: **lưu trữ có cấu trúc, ghi nhận lịch sử, phân quyền và tự động hóa**. Với người mới, không cần học hết các công cụ ngay. Hãy bắt đầu bằng Project, README, Commit và Branch; sau đó mới dùng Merge Request, CI/CD và Pages theo nhu cầu.

Nếu nội dung quan trọng, nguyên tắc đáng nhớ nhất là: *ai được sửa, sửa cái gì, ai duyệt, và có thể khôi phục không?*

[^projects]: Hướng dẫn chính thức: [Getting started with projects](https://docs.gitlab.com/user/get_started/get_started_projects/) (GitLab Docs, truy cập 10/2026).
[^webeditor]: Hướng dẫn chính thức: [Web Editor](https://docs.gitlab.com/user/project/repository/web_editor/) (GitLab Docs, truy cập 10/2026).
[^mr]: Hướng dẫn chính thức: [Merge requests](https://docs.gitlab.com/user/project/merge_requests/) (GitLab Docs, truy cập 10/2026).
[^members]: Hướng dẫn chính thức: [Project members and permissions](https://docs.gitlab.com/user/project/members/) (GitLab Docs, truy cập 10/2026).
[^gpages]: Hướng dẫn chính thức: [GitLab Pages](https://docs.gitlab.com/user/project/pages/) (GitLab Docs, truy cập 10/2026).
[^internal]: Theo [Project and group visibility](https://docs.gitlab.com/user/public_access/) (truy cập 10/2026), mục *Internal projects and groups* chỉ áp dụng cho GitLab Self-Managed và GitLab Dedicated, không có trên GitLab.com.
[^webide]: Theo [Web IDE](https://docs.gitlab.com/user/project/web_ide/) (truy cập 10/2026): từ một thư mục chọn **Code → Open in Web IDE**; từ một file chọn **Edit → Open in Web IDE**.
[^roles]: Theo [Roles and permissions](https://docs.gitlab.com/user/permissions/) (truy cập 10/2026), ngoài năm vai trò trên GitLab còn có Minimal Access, Planner (từ GitLab 17.7) và Security Manager (bản beta từ GitLab 18.11, đã bật trên GitLab.com). Planner và Security Manager là vai trò chuyên biệt, không bao gồm toàn bộ quyền của các vai trò khác.
[^pages]: Theo [GitLab Pages access control](https://docs.gitlab.com/user/project/pages/pages_access_control/) (truy cập 10/2026): vào **Settings → General → Visibility, project features, permissions**, đặt quyền truy cập Pages là **Everyone** để mọi người đọc được website, kể cả khi repository Private.