Deploy & Publish¶

Panduan proses build, tagging, dan auto deploy dokumentasi ke production.

Alur Deploy¶

Edit Konten → Git Push → Auto Build → Tag Version → Auto Deploy

Step 1: Edit & Commit¶

Setelah melakukan perubahan, commit dan push:

# Cek perubahan
git status

# Stage file yang berubah
git add docs/path/ke/file.md

# Commit
git commit -m "deskripsi perubahan"

# Push ke repository
git push origin main

Step 2: Build Otomatis¶

Setelah push, GitLab CI/CD otomatis akan:

1. Build Docker image dengan MkDocs
2. Push image ke container registry

Proses ini berjalan di background dan tidak perlu intervensi.

Step 3: Deploy ke Production¶

Deploy hanya terjadi saat membuat tag dengan format v*.*.*:

# Buat tag versi baru
git tag v0.3.0

# Push tag
git push origin v0.3.0

Format Versi¶

Gunakan Semantic Versioning:

v[MAJOR].[MINOR].[PATCH]

Cek Tag Terakhir¶

git tag -l --sort=-version:refname | head -5

Step 4: Verifikasi¶

Setelah deploy, cek site production:

1. Buka docs.garudea.com
2. Pastikan perubahan sudah tampil
3. Cek navigasi dan gambar

Testing Lokal Sebelum Deploy¶

Selalu test secara lokal sebelum push:

Preview dengan MkDocs¶

mkdocs serve

Build Strict (mendeteksi error)¶

mkdocs build --strict

Jika ada warning atau error, perbaiki sebelum push.

Test dengan Docker (opsional)¶

docker build -t garudea-docs-test .
docker run -d -p 8080:80 garudea-docs-test
# Buka http://localhost:8080

Troubleshooting¶

Build gagal¶

ERROR - Config value 'nav': ...

Penyebab: Path file di nav: salah atau file tidak ada. Solusi: Cek path file dan pastikan file .md sudah ada di lokasi yang benar.

Gambar tidak tampil¶

Penyebab: Nama file gambar tidak sesuai dengan referensi di markdown. Solusi: Pastikan nama file gambar sama persis (case-sensitive) dengan yang ditulis di markdown.

Warning MkDocs 2.0¶

WARNING – MkDocs 2.0 is incompatible with Material for MkDocs

Status: Ini hanya informasi, bukan error. Build tetap berhasil. Abaikan untuk saat ini.

Push gagal: "could not read Username"¶

fatal: could not read Username for 'https://repo.nusatek.id': No such device or address

Penyebab: Git belum menyimpan login untuk repo.nusatek.id. Solusi: Buat Personal Access Token di https://repo.nusatek.id/-/user_settings/personal_access_tokens (scope write_repository), lalu simpan sekali di terminal:

git config --global credential.helper store
git push   # masukkan username, dan token sebagai password

Setelah itu push berikutnya tidak perlu login lagi. Login tersimpan di ~/.git-credentials dalam bentuk teks biasa, jadi jangan salin atau commit file tersebut. Jika token kedaluwarsa, hapus baris repo.nusatek.id di file itu lalu ulangi langkah di atas.

Pipeline gagal: "tag does not exist" saat docker push¶

WARNING: No output specified with docker-container driver. Build result will only remain in the build cache.
...
tag does not exist: .../garudea/docs:v3.3.0

Penyebab: Runner GitLab memakai docker buildx dengan driver docker-container. Tanpa opsi --load, hasil build hanya tersimpan di cache dan tidak bisa di-push. Solusi: Pastikan perintah build di .gitlab-ci.yml memakai --load:

- docker buildx build --load . -t ${DOCKER}

Opsi ini sudah ditambahkan sejak v3.3.1. Jika error ini muncul lagi, cek apakah --load masih ada.

Deploy sebuah tag gagal¶

Status pipeline bisa dilihat di repo.nusatek.id/garudea/docs/-/pipelines.

Jika pipeline sebuah tag gagal karena masalah di repository (misalnya .gitlab-ci.yml):

1. Perbaiki masalahnya, lalu commit dan push ke main
2. Tambahkan entry versi PATCH baru di docs/references/releasenotes.md pada bagian ### Fixed
3. Buat dan push tag baru (misalnya v3.3.0 gagal → v3.3.1)