Đồng bộ Git

Giữ tài liệu SpecDown đồng bộ với repository GitHub hoặc GitLab. Mỗi lần lưu là một commit; mỗi push kích hoạt pull.

Kết nối Repository

1. Vào Cài đặt dự án → Git Integration.
2. Chọn nhà cung cấp: GitHub hoặc GitLab.
3. Nhập URL repository (ví dụ: https://github.com/org/repo).
4. Tạo Personal Access Token (PAT) với quyền đọc/ghi repo.
5. Dán PAT vào ô token và nhấn Connect.

Quyền PAT cần thiết

Cách đồng bộ hoạt động

Sau khi kết nối, SpecDown đồng bộ tài liệu như sau:

• Khi lưu: SpecDown commit tài liệu vào branch đã cấu hình, dùng full_path làm đường dẫn file với phần mở rộng .md.
• Khi push: Nếu repository nhận commit mới, SpecDown pull thay đổi và cập nhật tài liệu tương ứng.
• Xử lý xung đột: Last write wins. Nếu cùng file cập nhật ở cả SpecDown và Git, thay đổi mới nhất sẽ được giữ.

Cấu hình nhánh

Mặc định SpecDown đồng bộ với nhánh main. Bạn có thể đổi trong Cài đặt dự án → Git Integration → Target Branch.

Tài liệu tại đường dẫn guides/api/auth được commit thành:

docs/guides/api/auth.md

Thông báo commit

Commit theo định dạng:

docs(specdown): update "Authentication Guide"

Updated via SpecDown editor
User: user@example.com
Project: my-api-docs

Webhooks (Đồng bộ đến)

Để bật pull tự động khi repo nhận push, thiết lập webhook trên nhà cung cấp Git trỏ đến:

https://specdown.app/api/webhooks/git

Đặt Content-Type là application/json và dùng webhook secret hiển thị trong cài đặt dự án để ký payload.

Nhật ký đồng bộ

Mỗi thao tác đồng bộ (push hoặc pull) được ghi trong Cài đặt dự án → Git Logs. Log bao gồm commit SHA, thời gian, trạng thái (thành công / lỗi) và thông báo lỗi nếu có.

Giúp gỡ lỗi vấn đề đồng bộ mà không cần rời SpecDown.

Ngắt kết nối

Để ngắt đồng bộ Git, vào Cài đặt dự án → Git Integration và nhấn Disconnect. Tài liệu hiện có không bị ảnh hưởng — chỉ dừng đồng bộ tương lai. PAT sẽ bị xóa ngay khỏi database.