Cách kết nối Apidog với GitHub, GitLab

Nếu thông số kỹ thuật API của bạn nằm trong Apidog nhưng “source of truth” lại nằm trong Git, bạn cần một quy trình để hai bên luôn thống nhất. Tích hợp Git của Apidog giúp kết nối dự án Apidog với GitHub, GitLab hoặc Azure DevOps, sau đó đẩy OpenAPI spec vào hệ thống kiểm soát phiên bản và kéo thay đổi từ Git về Apidog khi cần. Kết quả: spec có lịch sử commit, có thể review bằng pull request, và có bản sao lưu an toàn nếu có sự cố trong ứng dụng.

Dùng thử Apidog hôm nay

Bài viết này tập trung vào cách triển khai thực tế: chọn provider, kết nối repository, thiết lập nhánh, đồng bộ hai chiều, sao lưu tự động và xử lý lỗi thường gặp. Nếu bạn chỉ cần hướng dẫn riêng cho GitHub, hãy xem bài viết về cách đồng bộ thông số kỹ thuật OpenAPI của bạn với GitHub.

Tích hợp Git của Apidog làm gì?

Apidog giao tiếp với Git theo hai cơ chế khác nhau. Trước khi cấu hình, bạn nên xác định rõ mình cần “đồng bộ” hay “sao lưu”.

1. Đồng bộ hai chiều bằng Spec-First Mode

Dùng khi bạn muốn xem OpenAPI spec như code:

• Sửa spec YAML/JSON trong Apidog.
• Commit thay đổi.
• Push lên nhánh Git đã kết nối.
• Pull thay đổi từ repository về Apidog khi đồng đội cập nhật spec từ Git.

Đây là workflow hai chiều: Apidog ↔ Git.

2. Sao lưu API spec tự động bằng Git

Dùng khi bạn chỉ cần bản sao có version trong Git:

• Apidog export OpenAPI/Swagger spec của từng module.
• Hệ thống tự động push file spec lên repository theo lịch.
• Không kéo thay đổi từ Git về Apidog.

Đây là workflow một chiều: Apidog → Git.

Tính năng	Hướng	Kích hoạt	Phù hợp với
Đồng bộ Spec-First Mode	Hai chiều: push và pull	Thủ công: commit/push/pull	Nhóm xem spec là code và muốn review mọi thay đổi
Sao lưu Git tự động	Một chiều: Apidog → Git	Theo lịch, ngoài giờ cao điểm	Nhóm muốn backup có version mà không đổi workflow

Quy ước trong bài:

• “Đồng bộ” = Spec-First Mode hai chiều.
• “Sao lưu” = export một chiều theo lịch.

Các nhà cung cấp Git được hỗ trợ

Apidog hỗ trợ các provider phổ biến sau:

Provider	Cách xác thực	Ghi chú triển khai
GitHub	OAuth bằng tài khoản GitHub	Hỗ trợ repository cá nhân và tổ chức. Repository thuộc organization có thể cần admin phê duyệt app.
GitLab	OAuth bằng tài khoản GitLab	Hỗ trợ gitlab.com và GitLab self-managed nếu Apidog truy cập được qua mạng.
Azure DevOps	Kết nối Git chung qua HTTPS + token	Dùng HTTPS clone URL và Personal Access Token có quyền repository.

Với Azure DevOps hoặc Git server tự host, bạn thường dùng “Generic Git Connection”. Miễn là server hỗ trợ Git qua HTTPS và xác thực bằng token, Apidog có thể kết nối theo luồng này.

Kết nối Git provider với Apidog

Quy trình tổng quát:

1. Chọn provider Git.
2. Cấp quyền truy cập repository.
3. Chọn repository.
4. Chọn nhánh.
5. Lưu cấu hình.
6. Kiểm tra push/pull hoặc cấu hình backup.

Kết nối GitHub

Với GitHub, bạn xác thực qua OAuth:

1. Trong Apidog, mở phần cấu hình Git của dự án.
2. Chọn GitHub.
3. Đăng nhập GitHub và cấp quyền repository.
4. Chọn repository cần đồng bộ.
5. Chọn nhánh, ví dụ main hoặc một feature branch.
6. Lưu cấu hình.

Lưu ý: nếu repository nằm trong GitHub Organization, admin có thể cần phê duyệt quyền truy cập của ứng dụng bên thứ ba trước khi Apidog nhìn thấy repository.

Kết nối GitLab

Với GitLab, luồng gần giống GitHub:

1. Chọn GitLab trong cấu hình Git.
2. Đăng nhập qua OAuth.
3. Cấp quyền repository.
4. Chọn repository và nhánh.
5. Lưu cấu hình.

Nếu dùng GitLab self-managed, hãy đảm bảo instance có thể được Apidog truy cập qua mạng.

Kết nối Azure DevOps

Azure DevOps dùng Generic Git Connection:

1. Vào Azure DevOps.
2. Mở repository cần kết nối.
3. Copy HTTPS clone URL.
4. Tạo Personal Access Token, giới hạn quyền đọc/ghi code cho repository cần dùng.
5. Trong Apidog, chọn Generic Git Connection.
6. Dán HTTPS clone URL.
7. Dán PAT.
8. Chọn nhánh và lưu.

Không nên dùng PAT có quyền toàn tài khoản. Hãy giới hạn scope theo repository hoặc project mục tiêu.

Checklist quyền truy cập trước khi đồng bộ

Trước khi triển khai cho team, kiểm tra các điểm sau:

• Repository cá nhân hay thuộc organization?
• Organization có chặn app bên thứ ba không?
• Người cấu hình có quyền ghi vào repository không?
• PAT có quyền đọc/ghi code không?
• Token có bị giới hạn sai project hoặc sai repository không?
• Repository là private hay public? Nếu private, token/OAuth đã đủ quyền chưa?
• Nhánh được chọn có đúng với workflow review của team không?

Nếu Apidog không thấy repository sau khi OAuth thành công, nguyên nhân phổ biến nhất là thiếu phê duyệt từ admin organization hoặc token thiếu scope.

Nếu bạn đang thiết kế convention cho spec trong Git, có thể xem thêm hướng dẫn về kiểm soát phiên bản OpenAPI bằng Git.

Đồng bộ hai chiều với Spec-First Mode

Spec-First Mode biến Apidog thành trình chỉnh sửa OpenAPI spec có thể commit vào Git. Bạn có thể xem thêm trong tài liệu chính thức của Apidog.

Workflow thực tế:

1. Mở spec trong Apidog.
2. Sửa YAML hoặc JSON.
3. Kiểm tra validation trong editor.
4. Commit thay đổi.
5. Push lên nhánh đã kết nối.
6. Khi đồng đội thay đổi spec trong Git, pull về Apidog.
7. Nếu có conflict, xử lý như conflict YAML thông thường.

Ví dụ thêm endpoint mới vào OpenAPI spec:

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

Sau khi lưu, Apidog đánh dấu đây là thay đổi cục bộ. Bạn commit với message rõ ràng, ví dụ:

Add getOrder endpoint to OpenAPI spec

Sau đó push lên nhánh đã kết nối.

Khi push thành công, trạng thái đồng bộ sẽ hiển thị kiểu “Đã đồng bộ hóa gần đây”, cho biết nội dung trong Apidog và nhánh Git đang khớp nhau.

Luồng pull từ Git về Apidog

Nếu đồng đội sửa spec trực tiếp trong repository và push trước bạn:

1. Mở dự án trong Apidog.
2. Pull thay đổi từ Git.
3. Kiểm tra lại spec trong editor.
4. Tiếp tục chỉnh sửa hoặc commit thay đổi mới.

Thói quen tốt: pull trước khi chỉnh sửa hoặc trước khi push. Điều này giảm khả năng conflict.

Khi nào nên discard thay đổi?

Nếu bạn thử nghiệm một thay đổi nhưng không muốn giữ:

1. Kiểm tra thay đổi cục bộ chưa push.
2. Dùng tùy chọn loại bỏ chỉnh sửa chưa đẩy.
3. Quay lại trạng thái đồng bộ gần nhất.

Cách này hữu ích khi bạn đang thử thiết kế endpoint, schema hoặc response nhưng quyết định không đưa vào spec.

Spec-First Mode phù hợp với quy trình làm việc API nguyên bản Git: spec đi qua commit, diff, pull request, review và rollback giống như code.

Sao lưu Git tự động cho API spec

Sao lưu tự động phù hợp khi bạn muốn Git giữ một bản copy có version nhưng không muốn team đổi workflow hằng ngày.

Cách hoạt động:

1. Bạn chọn module trong Apidog.
2. Cấu hình repository Git để sao lưu.
3. Apidog export OpenAPI/Swagger spec của module.
4. Hệ thống tự động push file spec vào repository theo lịch.
5. Mỗi lần push tạo commit mới, giúp bạn xem lịch sử thay đổi.

Các provider được hỗ trợ cho sao lưu gồm:

• Git
• GitHub
• GitLab
• Azure DevOps

Việc push backup diễn ra trong một khung thời gian ngẫu nhiên ngoài giờ cao điểm vào ban đêm. Điều này giúp tránh ảnh hưởng đến giờ làm việc và phân tán tải hệ thống.

Điểm cần nhớ: sao lưu là một chiều. Apidog ghi spec vào repository, nhưng không đọc thay đổi từ repository về. Nếu bạn cần Git → Apidog, hãy dùng Spec-First Mode.

Chọn nhánh và cấu trúc repository

Thiết kế Git structure ngay từ đầu sẽ giúp workflow ổn định hơn.

Chọn nhánh

Có hai lựa chọn phổ biến:

Đồng bộ trực tiếp với main

Phù hợp khi:

• Team nhỏ.
• Thay đổi spec ít rủi ro.
• Không cần pull request cho từng thay đổi.
• Muốn cấu hình đơn giản.

Nhược điểm: bỏ qua bước review trước khi spec trở thành bản chính.

Đồng bộ với feature branch

Phù hợp khi:

• Team muốn review spec bằng pull request.
• API contract cần được kiểm tra trước khi merge.
• Nhiều người cùng chỉnh sửa spec.
• Bạn muốn workflow giống code.

Ví dụ flow:

feature/update-order-api
        ↓
Pull Request
        ↓
Review YAML diff
        ↓
Merge vào main

Cách này an toàn hơn cho API public hoặc API có nhiều consumer.

Một repository hay nhiều repository?

Một repository cho mỗi API

Phù hợp khi:

• Mỗi API có owner riêng.
• Cần phân quyền chặt.
• Muốn lịch sử spec tách biệt.
• Muốn backup/sync đơn giản.

Ví dụ:

payment-api-spec/
order-api-spec/
user-api-spec/

Monorepo cho nhiều API spec

Phù hợp khi:

• Một platform team quản lý nhiều API.
• Muốn review spec tập trung.
• Muốn dễ tìm kiếm giữa nhiều API.

Ví dụ cấu trúc:

api-specs/
  orders/
    openapi.yaml
  payments/
    openapi.yaml
  users/
    openapi.yaml

Nếu dùng monorepo, hãy đảm bảo mỗi module có đường dẫn riêng để backup và diff không bị lẫn nhau.

Quyền và bảo mật thông tin xác thực

Tích hợp Git liên quan trực tiếp đến quyền đọc/ghi repository, vì vậy nên kiểm soát ở hai lớp: Apidog và Git provider.

Trong Apidog

Cấu hình ai có quyền:

• Xem spec.
• Chỉnh sửa spec.
• Đồng bộ với Git.
• Push thay đổi lên repository.

Khuyến nghị:

• Chỉ cấp quyền push cho người sở hữu API spec.
• Cho reviewer hoặc developer khác quyền đọc nếu họ không cần chỉnh sửa.
• Tránh để mọi thành viên đều có quyền push nếu spec là API contract quan trọng.

Trong Git provider

Với GitHub/GitLab, OAuth dùng quyền của user đã cấp quyền.

Với Azure DevOps hoặc Generic Git Connection, PAT chính là credential. Hãy xử lý PAT như secret:

• Không dán vào tài liệu chung.
• Không commit vào repository.
• Không chia sẻ qua chat công khai.
• Giới hạn scope vào repository/project cần dùng.
• Xoay vòng token định kỳ.
• Thu hồi token khi người sở hữu rời team.

Nguyên tắc: tích hợp chỉ an toàn bằng credential yếu nhất phía sau nó.

Xử lý conflict và drift

Vì Apidog commit vào Git thật, conflict cũng là conflict Git thật.

Ví dụ tình huống:

1. Bạn sửa schema Order trong Apidog.
2. Đồng đội sửa cùng schema trong repository.
3. Đồng đội push trước.
4. Bạn push hoặc pull sau.
5. Git phát hiện conflict trong file YAML.

Đây là conflict YAML thông thường. Cách xử lý:

1. Pull trạng thái mới nhất.
2. Mở file spec có conflict.
3. Chọn phần đúng từ mỗi phía.
4. Đảm bảo YAML vẫn hợp lệ.
5. Đảm bảo OpenAPI schema vẫn hợp lệ.
6. Commit lại.
7. Đồng bộ lại với Apidog.

Ví dụ conflict có thể trông như sau:

components:
  schemas:
    Order:
      type: object
      properties:
<<<<<<< HEAD
        status:
          type: string
          enum: [pending, paid, shipped]
=======
        status:
          type: string
          enum: [created, paid, cancelled]
>>>>>>> feature/update-order-status

Bạn cần quyết định enum cuối cùng, ví dụ:

components:
  schemas:
    Order:
      type: object
      properties:
        status:
          type: string
          enum: [created, pending, paid, shipped, cancelled]

Sau khi sửa, kiểm tra validation trong editor trước khi push tiếp.

Tránh drift giữa Apidog và Git

Drift xảy ra khi Apidog và repository âm thầm khác nhau trong thời gian dài.

Cách giảm drift:

• Pull trước khi chỉnh sửa.
• Push ngay sau khi commit thay đổi quan trọng.
• Không để nhiều thay đổi cục bộ tồn đọng.
• Theo dõi trạng thái “Đã đồng bộ hóa gần đây”.
• Dùng pull request để review thay đổi spec lớn.

Nếu trạng thái đồng bộ không hiển thị đúng, có thể bạn còn thay đổi chưa push hoặc repository có commit mới chưa pull.

Khắc phục sự cố thường gặp

Triệu chứng	Nguyên nhân có thể	Cách khắc phục
OAuth thành công nhưng repository không hiển thị	Organization chưa phê duyệt app, hoặc token thiếu scope	Nhờ admin phê duyệt app GitHub/GitLab. Với Azure DevOps, tạo lại PAT có quyền đọc/ghi code.
Push bị từ chối	Token bị thu hồi/hết hạn hoặc user không có quyền ghi	Ủy quyền lại provider hoặc cập nhật PAT mới trong Apidog.
Commit đã push nhưng không thấy ở nơi mong đợi	Chọn sai nhánh	Kiểm tra nhánh đã kết nối và nhánh đang xem trong repository.
Trạng thái đồng bộ không cập nhật	Còn thay đổi cục bộ chưa push hoặc cần pull commit mới	Commit/push thay đổi đang chờ. Nếu đồng đội đã push, pull trước rồi đồng bộ lại.
Conflict trong spec	Hai người sửa cùng dòng hoặc cùng schema	Resolve conflict YAML, kiểm tra OpenAPI validation, commit và sync lại.
Backup chưa chạy	Chưa đến lịch push ngoài giờ cao điểm	Chờ chu kỳ ban đêm tiếp theo hoặc kiểm tra lại cấu hình repository/nhánh backup.
Muốn bỏ thay đổi thử nghiệm	Có chỉnh sửa chưa commit/push	Dùng tùy chọn loại bỏ chỉnh sửa chưa đẩy để quay về trạng thái đồng bộ cuối.

Nếu lỗi lặp lại, bắt đầu bằng credential:

• Token còn hiệu lực không?
• Token có đúng scope không?
• User còn quyền ghi không?
• Organization có chặn app bên thứ ba không?
• Nhánh có bị branch protection chặn push không?

FAQ

Đồng bộ là một chiều hay hai chiều?

Tùy tính năng:

• Spec-First Mode là hai chiều: Apidog ↔ Git.
• Sao lưu tự động là một chiều: Apidog → Git.

Spec của tôi được lưu ở đâu?

Trong repository Git bạn kết nối.

• Với Spec-First Mode, OpenAPI document nằm trên nhánh bạn push tới.
• Với backup tự động, file OpenAPI/Swagger export của từng module được commit vào repository đã cấu hình.

Trong cả hai trường hợp, Git giữ lịch sử version và bạn kiểm soát repository.

Nên đồng bộ với nhánh nào?

Dùng:

• main cho spec chuẩn, ổn định.
• Feature branch cho thay đổi đang phát triển và cần review.

Nếu team đã dùng pull request cho code, nên áp dụng cùng cơ chế cho API spec.

Nếu token bị thu hồi thì sao?

Các lần push sẽ thất bại vì Apidog không còn quyền ghi.

Cách xử lý:

1. Ủy quyền lại GitHub/GitLab, hoặc
2. Tạo PAT mới cho Azure DevOps/Generic Git Connection.
3. Cập nhật credential trong Apidog.
4. Đồng bộ lại.

Sau khi credential hợp lệ, sync và backup sẽ tiếp tục hoạt động.

Kết luận

Tích hợp Git của Apidog cung cấp hai workflow bổ sung cho nhau:

• Spec-First Mode để đồng bộ hai chiều, phù hợp với nhóm xem OpenAPI spec là code.
• Sao lưu Git tự động để lưu bản copy có version mà không thay đổi quy trình làm việc hằng ngày.

Nếu bạn cần review mọi thay đổi API contract, hãy dùng Spec-First Mode với feature branch và pull request. Nếu bạn chỉ cần backup an toàn, hãy bật sao lưu tự động theo module. Nhiều nhóm có thể dùng cả hai: Spec-First cho workflow thiết kế chính và backup tự động như lớp bảo vệ bổ sung.