GitLab Integration¶

GitLab document integration hiển thị diagram trong repository Markdown, AsciiDoc hoặc wiki bằng public encoded GET. Self-managed GitLab có thể dùng custom image để chuyển params trên dòng mở fence trước khi Markdown được render.

1. Chọn cách hiển thị¶

Cách	Phù hợp khi	Thành phần cần thêm
Encoded image URL	Nhúng diagram đã có source hoàn chỉnh	Không
Markdown fence params	Muốn dùng `{...}` ngay cạnh source	GitLab custom image

Browser người đọc phải truy cập được Gateway qua HTTPS. Encoded URL không chứa token nhưng chứa source đã nén và có thể giải mã.

2. Nhúng bằng encoded GET¶

Route ảnh:

GET {SERVER_URL}/{renderer}/{format}/{encodedSource}

encodedSource là UTF-8 source được zlib DEFLATE rồi Base64 URL-safe. Tạo URL từ file diagram.puml bằng Node.js:

$encoded = node -e "const z=require('node:zlib'),f=require('node:fs');process.stdout.write(z.deflateSync(f.readFileSync(process.argv[1])).toString('base64url'))" diagram.puml
$url = "https://code-to-uml.example/plantuml/svg/$encoded"
$url

Markdown:

![Sequence diagram](https://code-to-uml.example/plantuml/svg/ENCODED_SOURCE)

AsciiDoc:

image::https://code-to-uml.example/plantuml/svg/ENCODED_SOURCE[Sequence diagram]

3. Params trong tài liệu GitLab¶

Source encode trực tiếp phải chứa %%krokup:

%%krokup {theme=corporate scale=1.5 direction=lr}
@startuml
Alice -> Bob: Review
@enduml

Trên GitLab có custom image, có thể đặt params trên fence:

```plantuml {theme=corporate scale=1.5 direction=lr} title="Review flow"
Alice -> Bob: Review
```

Filter chạy trước Markdown renderer, chuyển {...} thành đúng một dòng %%krokup, giới hạn theo renderer GitLab đã bật và giữ nguyên Markdown nếu bước chuyển đổi gặp lỗi. title chỉ là metadata và không được đưa vào render option.

Filter chỉ áp dụng cho Markdown trong repository blob và wiki. Các vùng Markdown khác của GitLab không đi qua pipeline này. Fence không có params hợp lệ và renderer bị tắt được giữ nguyên.

Giới hạn của filter:

Nội dung	Giới hạn
Markdown input	2 MiB
Fence được chuyển đổi	100 fence
Params của mỗi fence	1.024 byte

Fence params thắng %%krokup trong tối đa 20 dòng đầu body. Filter loại directive cũ trong vùng này trước khi chèn directive mới; Mermaid init block %%{...}%% vẫn được giữ nguyên.

4. Cài đặt GitLab custom image¶

Custom image hiện dựa trên GitLab CE 19.2.0-ce.0. Dockerfile, filter và test nằm trong deploy/gitlab-krokup/.

Build từ repository root:

docker build --file deploy/gitlab-krokup/Dockerfile `
  --tag gitlab-ce-kroki:19.2.0-ce.0-krokup `
  deploy/gitlab-krokup

Build context phải chứa đồng thời Dockerfile, lib/ và test/. Docker build kiểm tra vị trí Markdown pipeline trong GitLab image, chèn KrokupFenceFilter ngay trước MarkdownFilter và chạy unit test của rewriter. Build dừng nếu cấu trúc GitLab image không còn khớp.

Trong deployment self-managed GitLab, dùng tag vừa build thay cho image GitLab CE mặc định và giữ nguyên cấu hình instance, volume dữ liệu cùng reverse proxy. Manifest deploy/gitlab-krokup/compose.vps.yml chứa hostname, volume và proxy của instance hiện tại; deployment khác cần dùng các giá trị của chính instance đó.

Custom image sửa pipeline nội bộ của GitLab. Mỗi lần đổi GitLab version cần cập nhật base image, build lại và chạy đủ kiểm tra trước khi rollout.

5. Kiểm tra custom image¶

Mở repository blob chứa fence không có params và xác nhận diagram vẫn hiển thị.
Thêm {scale=2 theme=dark} vào fence và xác nhận output thay đổi.
Kiểm tra title, Mermaid init block và source đã có %%krokup.
Kiểm tra cùng nội dung trên wiki.
Thử renderer bị tắt, fence không đóng và params vượt giới hạn.
Kiểm tra log khi filter gặp lỗi và xác nhận Markdown ban đầu vẫn được render.

Pydia chạy Python source. Chỉ bật renderer này trong GitLab khi Code To UML deployment đã bật Pydia sandbox và policy dữ liệu cho phép thực thi source từ repository.

6. Cache và cập nhật¶

Thay source tạo encoded path mới. Cùng URL có thể được browser revalidate bằng ETag. Gateway áp dụng rate limit, result cache và request coalescing cho encoded GET.

7. Bảo mật và xử lý lỗi¶

Không đưa shared rendering token vào Markdown hoặc URL.
Không dùng encoded GET nếu source không được phép xuất hiện trong URL.
Với source dài hoặc nhạy cảm, render trong CI rồi lưu output theo policy của repository.
CSP của GitLab phải cho phép Gateway origin trong img-src.
Kiểm tra renderer và format bằng catalog runtime trước khi tạo URL.

Hiện tượng	Cách xử lý
Ảnh không tải	Mở URL trực tiếp, kiểm tra DNS, TLS và CSP
`404`	Kiểm tra renderer, format và encoded path
Params bị bỏ qua	Kiểm tra custom image, phạm vi blob/wiki và cú pháp `{...}`
Custom image không build	Kiểm tra GitLab base image và vị trí Markdown pipeline
Markdown không đổi	Kiểm tra renderer đã bật và giới hạn của filter
Ảnh cũ	Kiểm tra source có tạo encoded path mới và ETag revalidation