GitHub cơ bản cho BA

Tài liệu này dành cho ai

Tài liệu này dành cho:

• BA, PM, PO hoặc stakeholder chưa quen GitHub
• người chỉ mới nghe qua branch, commit, pull request
• người cần tham gia review hoặc bàn giao tài liệu qua GitHub nhưng không muốn học Git ở mức kỹ sư

Mục tiêu của tài liệu là giúp bạn hiểu đủ để làm việc an toàn trong repo BA-kit, không làm ảnh hưởng nội dung của người khác, và biết chính xác khi nào cần nhờ BA Lead hỗ trợ.

GitHub là gì theo cách dễ hiểu

Hãy hình dung:

• repository là kho tài liệu chung của dự án
• main là bản chính thức mới nhất mà cả team đang nhìn vào
• branch là một bản nhánh riêng để bạn làm việc mà không chạm trực tiếp vào bản chính thức
• commit là một lần lưu thay đổi có ghi chú
• pull request là yêu cầu xin đưa thay đổi từ branch của bạn vào main
• merge là hành động chấp nhận PR và đưa thay đổi đó vào bản chính thức

GitHub khuyến nghị cộng tác bằng cách tạo branch riêng, thực hiện thay đổi trên branch đó, rồi mở pull request để review trước khi merge vào branch chính. Trong BA-kit mới, đây là lớp GitHub handoff khi team cần PR/merge thật; BA team có thể điều phối trước bằng ba-collab, COLLAB-HOME.md, MODULE-HOME.md và review packet.

Những gì bạn cần có trước khi bắt đầu

Trước khi làm việc, bạn cần đủ 4 điều sau:

1. Có tài khoản GitHub.
2. Được BA Lead hoặc repo owner mời vào repo.
3. Đã bấm chấp nhận lời mời cộng tác.
4. Biết chính xác mình đang phụ trách module nào.

Nếu repo thuộc tài khoản cá nhân trên GitHub, GitHub Docs hiện mô tả repo private kiểu này chỉ có 2 mức quyền chính là owner và collaborators. Với repo private thuộc personal account, collaborator được cấp quyền ghi thay đổi; không có chế độ collaborator chỉ đọc.

Cách kiểm tra bạn đã vào đúng repo chưa

Khi mở repo trên GitHub, hãy nhìn tối thiểu các điểm sau:

1. Tên repo có đúng không.
2. Repo có hiển thị nhãn Private hay không.
3. Branch đang xem có phải main hay không.
4. Bạn có thấy tab Pull requests hay không.
5. Bạn có thấy nút tạo branch hoặc chỉnh sửa file hay không.

Nếu không thấy repo, thường là do một trong 3 lý do:

• bạn chưa được mời
• bạn đã được mời nhưng chưa accept
• bạn đang đăng nhập nhầm tài khoản GitHub

main là gì và vì sao không nên sửa trực tiếp

Trong workflow này:

• main là bản chính thức của initiative
• chỉ nội dung đã review xong mới nên vào main
• BA Member không nên sửa trực tiếp trên main

Lý do rất đơn giản:

• nếu nhiều người cùng sửa trực tiếp trên main, rất khó biết ai thay đổi gì
• khó review
• dễ ghi đè công việc của nhau
• khó rollback khi có lỗi

GitHub giải thích branch là một bản chụp của main tại thời điểm bạn tách nhánh. Vì vậy bạn nên tạo branch riêng, làm việc ở đó, rồi gửi PR về main.

branch là gì theo cách không kỹ thuật

Bạn có thể hiểu branch là “bản nháp cá nhân có kiểm soát”.

Ví dụ:

• main là bản tài liệu chính thức đang lưu trong tủ hồ sơ
• branch của bạn là bản photocopy bạn mang về bàn làm việc để chỉnh sửa
• khi chỉnh xong, bạn không tự ý thay bản gốc
• bạn gửi bản đã chỉnh cho lead review
• sau khi lead đồng ý, bản đó mới được cập nhật vào bản gốc

Trong BA-kit, mỗi BA Member nên có một branch riêng cho module mình phụ trách.

Ví dụ:

ba/warehouse-rfp/auth-flow
ba/warehouse-rfp/payment
ba/warehouse-rfp/inventory

commit là gì

commit là một lần lưu thay đổi kèm lời nhắn.

Bạn không cần quá ám ảnh về kỹ thuật của commit. Với người non-tech, chỉ cần nhớ:

• commit giúp ghi nhận “tôi đã thay đổi gì”
• commit giúp PR hiển thị lịch sử thay đổi
• nếu làm qua agent hoặc terminal, agent thường sẽ giúp tạo commit

Nếu bạn làm trực tiếp trên GitHub web, khi bấm lưu file, GitHub sẽ yêu cầu bạn nhập:

• Commit message: mô tả ngắn gọn thay đổi
• chọn commit trực tiếp lên branch hiện tại hoặc tạo branch mới

Trong collaboration workflow, bạn nên commit vào branch module của mình, không commit vào main.

pull request là gì

pull request hay PR là yêu cầu xin merge thay đổi từ branch của bạn vào branch đích, thường là main.

Hãy hiểu PR là:

• nơi tập trung thảo luận
• nơi lead review
• nơi nhìn thấy file nào đã đổi
• nơi quyết định có merge hay chưa

Theo GitHub Docs, pull request là tính năng cộng tác trung tâm của GitHub vì nó cho phép review và thảo luận trước khi thay đổi được đưa vào codebase hoặc bộ tài liệu chính.

Bên trong một Pull Request có gì

Khi mở PR, bạn sẽ thường thấy 4 khu vực quan trọng:

1. Conversation Đây là nơi mô tả phạm vi thay đổi, comment tổng quát, lịch sử review.
2. Commits Đây là nơi xem các lần lưu thay đổi đã được đẩy lên branch.
3. Checks Đây là nơi xem các kiểm tra tự động nếu repo có cấu hình CI.
4. Files changed Đây là nơi xem cụ thể file nào thay đổi và thay đổi ra sao.

Nếu bạn là người review, tab Files changed là nơi quan trọng nhất. Nếu bạn là người mở PR, Conversation là nơi bạn phải viết scope thật rõ.

Khi nào dùng Draft pull request

Bạn có thể mở Draft pull request khi:

• muốn lead nhìn sớm hướng làm
• muốn hỏi sớm về assumption
• tài liệu chưa hoàn thiện
• chưa muốn yêu cầu approve ngay

Draft PR rất hữu ích với người mới vì:

• bạn có thể xin feedback sớm
• giảm rủi ro làm sai hướng cả module
• tránh cảm giác “phải xong 100% mới được hỏi”

Khi tài liệu đã sẵn sàng review chính thức, bạn đổi trạng thái PR sang Ready for review.

Quy tắc làm việc an toàn cho người mới

Nếu bạn chỉ nhớ được vài điều, hãy nhớ 8 điều này:

1. Không sửa trực tiếp trên main.
2. Mỗi module dùng một branch riêng.
3. Một PR chỉ nên phục vụ một mục tiêu rõ ràng.
4. Không sửa file của module khác nếu chưa được giao.
5. Nếu scope chung thay đổi, báo BA Lead thay vì tự sửa âm thầm.
6. Trước khi mở PR, tự đọc lại tên file và thư mục mình vừa chạm.
7. Khi có comment review, sửa ngay trên chính branch đang mở PR.
8. Chỉ coi công việc hoàn tất sau khi PR được merge vào main.

Cách tạo branch trên GitHub web

Nếu bạn làm việc trực tiếp trên giao diện web của GitHub:

1. Mở repo.
2. Đứng ở branch main.
3. Bấm menu chọn branch.
4. Gõ tên branch mới.
5. Chọn tạo branch từ main.

GitHub Docs ghi rõ: bạn chỉ có thể tạo branch trong repo mà bạn có quyền push.

Cách chỉnh file trực tiếp trên GitHub web

Nếu bạn chỉ cần sửa một file markdown nhỏ:

1. Mở đúng file cần sửa.
2. Bấm biểu tượng bút chì để edit.
3. Sửa nội dung.
4. Kéo xuống phần commit.
5. Điền commit message ngắn, rõ.
6. Chọn commit vào branch của bạn, không phải main.
7. Lưu thay đổi.

Nếu repo có protected branch, GitHub có thể không cho sửa trực tiếp lên branch được bảo vệ.

Cách mở Pull Request trên GitHub web

Luồng đơn giản nhất là:

1. Vào repo.
2. Mở branch của bạn.
3. Bấm Contribute hoặc Open pull request nếu GitHub gợi ý.
4. Kiểm tra:
   • base branch là main
   • compare branch là branch của bạn
5. Viết tiêu đề PR thật rõ.
6. Viết mô tả PR theo scope được giao.
7. Nếu chưa sẵn sàng review, tạo Draft pull request.
8. Nếu sẵn sàng, tạo PR thường và request lead review.

GitHub Docs nhấn mạnh rằng thay đổi được đề xuất trong một branch để đảm bảo default branch chỉ chứa công việc đã hoàn thành và được duyệt.

Sau khi mở PR thì làm gì

Sau khi PR đã mở:

1. Đọc comment ở tab Conversation.
2. Xem lead comment trực tiếp ở Files changed.
3. Cập nhật tài liệu trên chính branch đang mở PR.
4. Push hoặc commit thêm thay đổi mới.
5. Quay lại PR để xác nhận comment đã được xử lý.

Bạn không cần mở PR mới cho cùng một scope, trừ khi lead yêu cầu tách PR.

Review là gì và lead sẽ làm gì

Khi review PR, lead thường sẽ:

• xem phạm vi thay đổi có đúng module không
• xem file nào bị sửa
• comment vào từng đoạn chưa rõ
• Approve nếu đồng ý
• Request changes nếu cần sửa thêm

GitHub Docs hướng dẫn review theo từng file trong tab Files changed, có thể comment vào từng dòng thay đổi và đánh dấu file là Viewed để theo dõi tiến độ review.

merge là gì

merge là bước GitHub đưa thay đổi từ branch của bạn vào main.

Với BA Member, điều quan trọng cần nhớ:

• không phải cứ mở PR là xong
• PR chỉ hoàn tất khi đã được merge
• sau khi merge, branch cũ có thể được xóa để repo gọn hơn

Vì sao cần kéo thay đổi mới nhất từ main

Vì main liên tục được cập nhật khi các PR khác được merge.

Nếu bạn làm trên branch cũ quá lâu mà không cập nhật:

• bạn có thể viết dựa trên thông tin đã cũ
• PR dễ bị xung đột
• nội dung có thể lệch khỏi backbone mới nhất

GitHub giải thích rằng branch là ảnh chụp của main tại thời điểm tạo nhánh. Nếu main thay đổi trong lúc bạn đang làm, bạn cần cập nhật branch của mình để bám bản mới.

Khi nào cần báo BA Lead ngay thay vì tự xử

Hãy báo lead ngay nếu gặp một trong các tình huống sau:

• bạn không thấy repo hoặc không vào được repo
• không tạo được branch
• không mở được PR
• bạn phát hiện thay đổi cần chạm backbone
• có file của module khác bị kéo vào PR
• PR báo conflict
• bạn không chắc thay đổi này là module-level hay system-level

Những lỗi người mới hay gặp

1. Sửa nhầm trên main

Đây là lỗi nghiêm trọng nhất. Nếu thấy branch đang là main, dừng lại trước khi edit.

2. Một PR chứa nhiều module

Điều này làm lead khó review và khó rollback. Mỗi PR nên có một trọng tâm rõ ràng.

3. Không đọc lại base branch

Có người mở PR nhầm từ branch của mình sang một branch khác thay vì main. Trước khi bấm tạo PR, luôn kiểm tra lại base.

4. Tự sửa cả phần scope chung

Nếu thấy rule chung sai, đừng “sửa cho tiện”. Hãy báo lead để lead xử lý theo luồng impact hoặc backbone update.

5. Tưởng comment review chỉ để đọc

Comment review là việc cần xử lý. Nếu lead Request changes, PR chưa nên merge.

Cấu hình GitHub tối thiểu BA Lead nên hiểu

Nếu bạn là BA Lead hoặc repo owner, hãy nắm 4 điểm này:

1. Collaborators Dùng để mời thành viên vào repo.
2. Default branch Thường là main.
3. Pull request merge options Nên thống nhất dùng Squash and merge hoặc một phương án rõ ràng.
4. Branch protection Dùng để hạn chế push trực tiếp hoặc yêu cầu review trước khi merge.

Lưu ý quan trọng:

• GitHub Docs hiện nêu rằng protected branches trên repo private không phải plan nào cũng có.
• Nếu team đang dùng repo private trên personal account nhưng plan không hỗ trợ branch protection, hãy áp dụng quy ước vận hành chặt chẽ bằng con người:
  • không ai sửa trực tiếp main
  • mọi thay đổi đi qua PR
  • chỉ lead hoặc maintainer merge

Nguồn tham khảo chính thức

Tài liệu này được đối chiếu với GitHub Docs chính thức ngày 2026-04-23:

• Hello World: https://docs.github.com/en/get-started/start-your-journey/hello-world
• About pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
• Creating a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
• Reviewing proposed changes in a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request
• Managing access to your personal repositories: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration
• Permission levels for a personal account repository: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository
• Creating and deleting branches within your repository: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/creating-and-deleting-branches-within-your-repository
• About protected branches: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches