> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skanesgalab.my.id/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab CI/CD Pipeline

> Panduan lengkap GitLab CI/CD: konsep dasar, arsitektur GitLab Runner, konfigurasi .gitlab-ci.yml, stages, artifacts, cache, hingga teknik tingkat lanjut (rules, environments, DinD).

## Apa itu GitLab CI/CD?

**GitLab CI/CD** adalah sistem otomatisasi bawaan (*built-in*) yang menjadi bagian tak terpisahkan dari platform GitLab. Tanpa perlu memasang plugin tambahan pihak ketiga, GitLab menyediakan ekosistem terpadu mulai dari repositori kode, manajemen issue, pipeline CI/CD, Container Registry terintegrasi, hingga pemantauan deployment.

***

## Arsitektur GitLab CI/CD: Coordinator vs Runner

Alur kerja GitLab CI/CD ditopang oleh dua komponen utama:

```mermaid theme={null}
flowchart TD
    GitLab["GitLab Server / SaaS (Coordinator)\n- Membaca berkas .gitlab-ci.yml\n- Mengelola antrean pekerjaan (Jobs)\n- Dashboard Pipeline & UI"]
    
    subgraph Runners["GitLab Runner Instances"]
        R1["Shared Runner (Cloud SaaS)"]
        R2["Specific / Self-Hosted Runner (Docker Executor)"]
        R3["Kubernetes Runner (Autoscaled Pods)"]
    end

    GitLab -->|Membagi Jobs via HTTPS API| R1
    GitLab -->|Membagi Jobs via HTTPS API| R2
    GitLab -->|Membagi Jobs via HTTPS API| R3
```

1. **GitLab Instance (Coordinator):** Mengelola antrean job, memvalidasi sintaks berkas `.gitlab-ci.yml`, dan menyajikan status keberhasilan pipeline di antarmuka web.
2. **GitLab Runner:** Agen perangkat lunak mandiri yang bertugas mengeksekusi perintah-perintah di dalam job. Runner dapat berjalan di mesin Linux lokal, container Docker, atau kluster Kubernetes.

***

## Konfigurasi Berkas `.gitlab-ci.yml`

Seluruh alur kerja didefinisikan dalam sebuah berkas bernama `.gitlab-ci.yml` yang disimpan di direktori akar (*root*) repositori proyekmu.

### Struktur Dasar Pipeline

```yaml theme={null}
# Menentukan base image docker default untuk menjalankan skrip
image: node:18-alpine

# Mendefinisikan tahapan-tahapan yang akan dieksekusi secara berurutan
stages:
  - lint
  - test
  - build
  - deploy

# Job 1: Pengecekan standar kode
lint-code:
  stage: lint
  script:
    - npm ci
    - npm run lint

# Job 2: Menjalankan pengujian otomatis
unit-test:
  stage: test
  script:
    - npm ci
    - npm test

# Job 3: Perakitan build aplikasi
build-artifact:
  stage: build
  script:
    - npm run build
  artifacts:
    name: "production-build-$CI_COMMIT_SHORT_SHA"
    paths:
      - dist/
    expire_in: 1 week

# Job 4: Deployment ke server
deploy-staging:
  stage: deploy
  script:
    - echo "Deploying artifact to staging server..."
  environment:
    name: staging
    url: https://staging.myapp.com
```

***

## Komponen Esensial GitLab CI

### 1. Artifacts vs Cache

Sering kali pemula bingung membedakan antara `artifacts` dan `cache`:

| Fitur | Tujuan Utama | Kapan Digunakan |
| :- | :- | :- |
| **`cache`** | Mempercepat waktu build antar job/pipeline. | Menyimpan folder dependensi (seperti `node_modules` atau file cache Maven). |
| **`artifacts`** | Mengirimkan hasil output satu job ke job berikutnya (atau diunduh via web UI). | Menyimpan binary hasil kompilasi, folder `dist/`, atau laporan coverage tes. |

Contoh penggunaan `cache`:

```yaml theme={null}
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .npm/
```

### 2. Variabel Rahasia (CI/CD Variables)

Untuk menyimpan kredensial database, password server, atau token registry:

1. Buka repositori GitLab $\to$ **Settings** $\to$ **CI/CD**.
2. Perluas bagian **Variables** $\to$ klik **Add variable**.
3. Centang opsi **Protect variable** (hanya berlaku di branch terlindungi) dan **Mask variable** (agar nilainya disensor bintang `***` di log terminal).
4. Gunakan langsung di skrip menggunakan format `$NAMA_VARIABEL`:

```yaml theme={null}
deploy-job:
  stage: deploy
  script:
    - sshpass -p "$SERVER_PASSWORD" ssh $SERVER_USER@$SERVER_IP "systemctl restart myapp"
```

***

## Fitur Tingkat Lanjut (Advanced GitLab CI)

### 1. Kontrol Eksekusi Fleksibel (`rules`)

Mengatur kapan sebuah job boleh berjalan atau dilewati berdasarkan branch, tag, atau isi pesan commit:

```yaml theme={null}
deploy-production:
  stage: deploy
  script:
    - ./deploy-to-prod.sh
  rules:
    # Hanya berjalan jika commit berada di branch 'main' dan tipenya BUKAN merge request biasa
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual # Membutuhkan klik manual persetujuan dari tim engineer
    - when: never # Selain kondisi di atas, abaikan job ini
```

### 2. Docker in Docker (DinD) — Membangun Image di Pipeline

Jika aplikasimu ingin dibungkus menjadi Docker Image dan diunggah ke **GitLab Container Registry**:

```yaml theme={null}
build-docker-image:
  stage: build
  image: docker:24-cli
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
```

### 3. Lingkungan & Rollback (`environment`)

Fitur dasbor pelacakan deployment bawaan GitLab yang memungkinkan tim melihat versi kode apa yang saat ini aktif di server serta tombol rollback otomatis:

```yaml theme={null}
deploy-prod:
  stage: deploy
  script:
    - ansible-playbook deploy.yml
  environment:
    name: production
    url: https://myapp.com
    on_stop: stop-prod
```

### 4. Menggunakan Multi-Project Pipeline (`trigger`)

Dalam arsitektur Microservices, ketika satu repositori pustaka (misal `core-library`) mengalami perubahan, ia dapat secara otomatis memicu (*trigger*) pipeline pada repositori aplikasi backend atau frontend yang bergantung padanya:

```yaml theme={null}
trigger-frontend-build:
  stage: deploy
  trigger:
    project: company/frontend-web
    branch: main
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.