Docker dalam CI

Pipeline build, test, dan push di GitHub Actions, termasuk cache dan penandaan image CI.

Daftar isi

Perintah docker build dan docker run yang dijalankan manual di terminal dapat diotomasi, dan tempatnya adalah sistem CI. Topik ini membahas pipeline, yaitu rangkaian langkah otomatis yang dieksekusi setiap kali kode dikirim ke repositori. Cakupannya meliputi urutan tahap yang lazim untuk aplikasi Docker, contoh workflow utuh berupa alur kerja berkas YAML pada GitHub Actions, cara kredensial disimpan, penandaan image hasil CI, dan cache build. Setelah topik ini dibaca, setiap pengiriman kode ke cabang utama dapat menghasilkan image yang teruji, bertanda jelas, dan siap ditarik dari registry, server tempat image disimpan dan dibagikan.

Urutan tahap pipeline#

Pipeline Docker yang lazim mengikuti urutan tahap berikut, dan setiap tahap hanya dijalankan bila tahap sebelumnya berhasil.

Lint dan uji, yaitu pemeriksaan kualitas kode secara otomatis serta pengujian aplikasi tanpa Docker.
Bangun image dari Dockerfile dengan docker build.
Beri penanda pada image, berupa versi semantik dan jejak commit, rekaman perubahan pada git.
Unggah image ke registry agar seluruh anggota tim menarik artefak yang sama.
Deploy, yaitu penyebaran image ke server yang berjalan, dan tahap ini opsional karena sering ditangani pipeline terpisah.

Diagram berikut merangkum urutan tahap tersebut.

Urutan tahap pipeline Docker yang lazim

Tahap-tahap ini terlebih dahulu dijalankan manual untuk memastikan urutannya benar, baru diotomasi pada workflow. Dua perintah berikut meniru tahap bangun dan uji image secara lokal.

bash

# tidak-dijalankan: daemon Docker tidak tersedia di sandbox
# menguji build secara lokal sebelum alur yang sama diotomasi
docker build -t budi/catatan:uji-lokal .

bash

# tidak-dijalankan: daemon Docker tidak tersedia di sandbox
# menyalakan container hasil build lokal untuk pengujian singkat
docker run --rm -p 8000:8000 budi/catatan:uji-lokal

Alasan image dibangun di CI, bukan di komputer masing-masing anggota tim, adalah kepastian artefak. Image yang dihasilkan CI berasal dari kode pada commit tertentu, dibangun di lingkungan yang sama setiap waktu, dan menjadi satu-satunya artefak yang diuji sekaligus dijalankan di mana pun. Registry kemudian menjadi titik temu, karena setiap pihak menarik image yang sama alih-alih membangun versi sendiri.

Workflow utuh di GitHub Actions#

Workflow pada GitHub Actions ditulis sebagai berkas YAML di direktori .github/workflows/ repositori, dan berkas itu menyatakan pemicu serta pekerjaan yang dijalankan. Berkas deploy.yml berikut adalah workflow utuh untuk aplikasi catatan, dengan pekerjaan pengujian yang mendahului pekerjaan build dan unggah.

yaml deploy.yml

# Alur kerja CI aplikasi catatan: uji, bangun, lalu unggah image
name: deploy

on:
  push:
    branches:
      - main

env:
  IMAGE: budi/catatan
  VERSI: "1.4.0"

jobs:
  uji:
    name: Pengujian aplikasi
    runs-on: ubuntu-latest
    steps:
      - name: Mengambil kode repositori
        uses: actions/checkout@v4

      - name: Menyiapkan Python 3.12
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Menjalankan pengujian
        run: python3 -m unittest

  unggah:
    name: Bangun dan unggah image
    needs: uji
    runs-on: ubuntu-latest
    steps:
      - name: Mengambil kode repositori
        uses: actions/checkout@v4

      - name: Menyiapkan BuildKit
        uses: docker/setup-buildx-action@v3

      - name: Masuk ke Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Membangun dan mengunggah image
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            ${{ env.IMAGE }}:${{ env.VERSI }}
            ${{ env.IMAGE }}:sha-${{ github.sha }}
            ${{ env.IMAGE }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

Strukturnya dapat dibaca bagian demi bagian. Kunci on menetapkan pemicu berupa push ke cabang utama, yaitu pengiriman kode ke repositori. Kunci env menampung IMAGE dan VERSI yang dipakai ulang di sepanjang berkas. Dua pekerjaan dijalankan berurutan, yaitu uji dan unggah, dan kunci needs: uji pada pekerjaan kedua memastikan unggah hanya terjadi bila pengujian lulus.

Pekerjaan uji menjalankan pengujian langsung dengan Python, dan perintahnya disesuaikan dengan proyek masing-masing. Pekerjaan unggah menyiapkan BuildKit, masuk ke Docker Hub, lalu membangun dan mengunggah image melalui docker/build-push-action dengan context: . dan push: true. Nilai VERSI diperbarui secara manual pada setiap rilis, dan workflow yang lebih lanjut biasanya mengambilnya dari tag git.

Kredensial dari secrets repositori#

Langkah masuk ke Docker Hub memakai dua nilai dari secrets, yaitu secrets.DOCKERHUB_USERNAME dan secrets.DOCKERHUB_TOKEN. Token di sini berarti pengganti kata sandi yang ruang lingkupnya terbatas dan dapat dicabut kapan saja, sehingga lebih aman daripada kata sandi akun. Kedua nilai tersebut dikonfigurasi pada pengaturan repositori GitHub, tepatnya melalui menu Settings lalu Secrets and variables lalu Actions, dan tidak pernah ditulis pada berkas workflow. Nilai secrets disamarkan pada log pekerjaan, tetapi penyamaran itu tidak berlaku pada berkas workflow, karena teks yang ditulis langsung pada deploy.yml tetap terbaca oleh semua orang yang membuka repositori.

Pola secrets ini sama dengan pola pada topik Penanganan Secret, yaitu kredensial disimpan di tempat yang dikelola khusus lalu disuntikkan saat dibutuhkan. Perbedaannya hanya pada tempat penyimpanan. Di sini pengelolanya adalah platform CI, sedangkan nilainya tetap tidak pernah muncul pada berkas apa pun di repositori.

Penandaan image dari CI#

Daftar tags pada langkah build menghasilkan tiga penanda untuk satu image yang sama. Penanda ${{ env.VERSI }} membawa nomor versi semantik sesuai konvensi yang dibahas pada modul Registry. Penanda sha-${{ github.sha }} mengaitkan image dengan commit yang membangunnya, sehingga image apa pun pada registry dapat dilacak kembali ke kode asalnya dan dipulihkan dengan tepat. Penanda latest tetap ditulis karena workflow hanya menyala pada push ke cabang utama, sehingga penanda yang selalu berpindah itu hanya diunggah dari cabang utama.

Aturan yang perlu dijaga adalah tidak pernah mengunggah satu penanda saja. Image yang hanya bertanda latest menyembunyikan versi dan commit asalnya, sehingga tidak ada cara tepat untuk mengembalikan rilis sebelumnya. Jejak commit sha- menutup celah itu tanpa biaya tambahan, karena nilainya diberikan otomatis oleh platform CI. Apabila kelak workflow juga dijalankan untuk cabang lain, latest dikeluarkan dari daftar tags atau diberi syarat agar tidak tergantikan oleh build yang belum lulus uji.

Cache build dengan type=gha#

Setiap eksekusi workflow berjalan pada runner, mesin kerja sementara yang disiapkan platform untuk satu pekerjaan lalu dibuang. Mesin yang selalu baru membuat cache layer build selalu kosong, sehingga seluruh layer, termasuk pemasangan paket yang paling lama, dibangun ulang pada setiap push. Dua baris pada langkah build menyelesaikan masalah tersebut. Baris cache-from: type=gha menarik cache dari penyimpanan cache GitHub Actions milik repositori, sedangkan baris cache-to: type=gha,mode=max menuliskannya kembali setelah build selesai. Nilai mode=max menyimpan layer dari seluruh tahap build, bukan hanya tahap terakhir, sehingga cache tetap berguna meski Dockerfile berubah.

Cache ini terpisah dari cache build lokal karena berada di sisi layanan CI dan mengikuti repositorinya. Ukurannya dibatasi oleh platform, sehingga cache terbaru perlahan menggantikan cache yang lebih tua. Dengan cache tersebut, layer yang tidak berubah diambil dari penyimpanan, dan build kembali secepat build lokal yang cache-nya sudah terisi.

Ringkasan#

Pipeline Docker lazim berurutan lint dan uji, bangun image, penandaan, unggah registry, dengan deploy sebagai tahap opsional.
Workflow GitHub Actions menjalankan pekerjaan uji lebih dahulu, lalu membangun dan mengunggah image melalui docker/build-push-action dengan context: . dan push: true.
Kredensial diambil dari secrets.DOCKERHUB_USERNAME dan secrets.DOCKERHUB_TOKEN yang dikonfigurasi pada pengaturan repositori, bukan ditulis pada berkas workflow.
Image ditandai versi semantik, sha-${{ github.sha }}, dan latest yang hanya diunggah dari cabang utama, sedangkan cache type=gha menjaga build tetap cepat.

Referensi#

GitHub Actions — Docker Docs — Panduan resmi membangun dan mengunggah image dengan GitHub Actions.
Building images in CI — Docker Docs — Praktik umum pipeline build image pada sistem CI.