VPS Murah Nevacloud

Push ke Forgejo, Build Jalan Sendiri: Woodpecker CI di VPS Tanpa GitHub

Commit sudah mendarat di repo Forgejo, kode rapi, tag rilis menunggu. Tapi tes dan build masih jalan di mesin lain, dengan akun dan kuota yang bukan milik kita. Situasi ini yang membuat banyak orang akhirnya menyerah: git server sudah mandiri, sementara pipelinenya masih menumpang. Oke, lanjuutt.. Di artikel ini kita pasang Woodpecker CI di Forgejo supaya setiap push langsung memicu build di VPS yang sama, tanpa satu baris pun dikirim ke GitHub.

Woodpecker versi terbaru saat artikel ini ditulis adalah 3.20.1, rilis 29 Oktober 2026. Dokumentasi resminya juga sudah memakai jalur 3.20, jadi seluruh variabel yang kita pakai di bawah ini cocok dengan versi tersebut.

Kenapa Woodpecker, Bukan Runner Bawaan Forgejo

Forgejo sebenarnya sudah punya unit Actions sendiri (terlihat di daftar DEFAULT_REPO_UNITS pada config cheat sheet-nya), tapi untuk VPS kecil Woodpecker tetap punya beberapa kelebihan:

  • Forgejo adalah forge resmi yang didukung. Tidak ada simulasi GitHub; autentikasi, izin repo, dan webhook dibaca langsung dari Forgejo.
  • Agent terpisah dari server. Server boleh kecil, agent bisa ditaruh di mesin lain kalau build-nya berat.
  • Pipeline-nya YAML biasa di .woodpecker.yaml, tanpa runner yang harus didaftarkan lebih dulu per repo.
  • Event deployment ada, tapi harus dinyalakan. Namanya deployment, bukan deploy, dan bisa dipicu dari Woodpecker sendiri lewat pengaturan proyek Allow deployments: pipeline yang sukses boleh memulai pipeline deploy. GitHub juga mendukung pemicu lewat webhook, tapi di Forgejo jalur yang tersedia adalah pengaturan proyek itu plus tombol manual. Kalau alur rilis kita bergantung pada deploy otomatis, nyalakan opsi tersebut dan sadari risikonya: siapa pun yang bisa push bisa mencuri secret khusus event deploy.

Langkah 1: Daftarkan Aplikasi OAuth di Forgejo

Woodpecker tidak punya pendaftaran pengguna sendiri. Semua identitas datang dari forge lewat OAuth2, jadi langkah pertama ada di Forgejo.

  1. Buka https://git.contoh.com/user/settings/applications.
  2. Isi nama aplikasi, misalnya woodpecker.
  3. Isi Redirect URI dengan https://ci.contoh.com/authorize. Path /authorize ini wajib, dan skema serta hostname harus sama persis dengan alamat Woodpecker. Sedikit beda http vs https saja, login akan gagal.
  4. Simpan, lalu catat Client ID dan Client Secret.

Kalau kita admin di kedua layanan, ada opsi aplikasi system-wide di https://git.contoh.com/admin/settings/applications. Bedanya: aplikasi ini terlihat oleh semua pengguna dan tidak terkena kuota aplikasi per akun, cocok untuk instance yang dipakai bersama.

Langkah 2: Izinkan Webhook Lokal di app.ini

Ini bagian yang paling sering dilupakan dan gejalanya menyesatkan: repo aktif, tombol build ada, tapi pipeline tidak pernah jalan sendiri.

Forgejo membatasi tujuan webhook demi keamanan. Nilai bawaan ALLOWED_HOST_LIST di bagian [webhook] adalah external, artinya hanya host publik yang boleh dipanggil. Kalau Woodpecker dan Forgejo berada di jaringan yang sama dan saling memanggil lewat alamat internal, webhook-nya ditolak.

Tambahkan di app.ini Forgejo (biasanya /etc/forgejo/app.ini atau custom/conf/app.ini):


[webhook]
ALLOWED_HOST_LIST = external,loopback

loopback mencakup 127.0.0.0/8 dan ::1. Kalau alamat internal kita bukan loopback, misalnya nama kontainer di jaringan Docker, tambahkan jaringan itu atau tulis CIDR-nya langsung.

Satu hal lagi yang sering terlewat: jangan turunkan MAX_RESPONSE_ITEMS di bagian [api] di bawah 50. Nilai bawaannya 50, dan dokumentasi Woodpecker menyebut sebagian fiturnya tidak bekerja benar kalau halaman API dibatasi lebih kecil dari itu.

Setelah mengubah app.ini, restart Forgejo. Konfigurasi Forgejo hanya terbaca ulang saat layanan dinyalakan kembali.

Langkah 3: Susun docker-compose untuk Server dan Agent

Woodpecker terdiri dari dua bagian: server yang menyimpan data dan web UI, dan agent yang menjalankan setiap step sebagai kontainer. Keduanya memakai image woodpeckerci/woodpecker-server:v3 dan woodpeckerci/woodpecker-agent:v3.

Buat .env di samping compose file. Jangan menaruh rahasia langsung di YAML yang ikut ter-commit:


openssl rand -hex 32

Simpan hasilnya sebagai WOODPECKER_AGENT_SECRET, ditambah client id dan secret dari langkah 1:


WOODPECKER_HOST=https://ci.contoh.com
WOODPECKER_AGENT_SECRET=isi-hasil-openssl
WOODPECKER_FORGEJO_CLIENT=client-id-dari-forgejo
WOODPECKER_FORGEJO_SECRET=client-secret-dari-forgejo

Lalu docker-compose.yml:


services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3
    restart: always
    ports:
      - "8000:8000"
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_FORGEJO=true
      - WOODPECKER_FORGEJO_URL=https://git.contoh.com
      - WOODPECKER_FORGEJO_CLIENT=${WOODPECKER_FORGEJO_CLIENT}
      - WOODPECKER_FORGEJO_SECRET=${WOODPECKER_FORGEJO_SECRET}
      - WOODPECKER_OPEN=true
      - WOODPECKER_ADMIN=donny
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
    networks:
      - forgejo

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3
    command: agent
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - woodpecker-agent-config:/etc/woodpecker
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
      - WOODPECKER_BACKEND_DOCKER_NETWORK=forgejo
    networks:
      - forgejo

volumes:
  woodpecker-server-data:
  woodpecker-agent-config:

networks:
  forgejo:
    external: true

Beberapa hal yang perlu dibaca lambat-lambat:

  • Port 8000 untuk HTTP, 9000 untuk gRPC. Agent tidak memakai 8000; dia bicara ke server lewat 9000 di jaringan internal. Jangan buka 9000 ke internet.
  • WOODPECKER_HOST harus alamat publik lengkap dengan skema, tanpa garis miring di akhir. Nilai ini yang dipakai untuk callback OAuth dan untuk menyusun URL webhook.
  • WOODPECKER_OPEN bawaannya false, artinya pendaftaran tertutup dan pengguna dikelola manual. Untuk instance pribadi, true plus WOODPECKER_ADMIN lebih praktis. Tapi ingat sifat daftar itu: WOODPECKER_ADMIN hanya memberi hak admin saat login, tidak pernah mencabutnya. Kalau kita menghapus nama dari daftar tapi tidak mencabut admin di pengaturan, orang itu kembali jadi admin pada login berikutnya setelah server restart.
  • Jaringan forgejo diambil dari compose Forgejo yang sudah kita pasang sebelumnya. WOODPECKER_BACKEND_DOCKER_NETWORK=forgejo membuat step build ikut jaringan itu, sehingga bisa menjangkau Forgejo lewat nama internal.

Nyalakan dengan docker compose up -d, lalu taruh reverse proxy di depan port 8000 dan pastikan HTTPS aktif. Reverse proxy wajib meneruskan header X-Forwarded-Proto dan Host, karena OAuth callback membandingkan keduanya.

Langkah 4: Aktifkan Repo dan Tulis Pipeline Pertama

Buka https://ci.contoh.com, login lewat Forgejo, lalu pilih repo yang mau diaktifkan. Syaratnya kita punya hak Admin di repo tersebut, karena Woodpecker perlu memasang webhook di sana.

Lalu buat .woodpecker.yaml di akar repo:


when:
  - event: push
    branch: main

steps:
  - name: test
    image: node:22
    commands:
      - npm ci
      - npm test

  - name: build
    image: node:22
    commands:
      - npm run build

Isinya: satu workflow, dua step berurutan, satu workspace. Kalau tes gagal, build dilewati dan pipeline berhenti dengan status error. Beberapa detail yang menghemat waktu:

  • Lokasi file bukan hanya satu. Urutan pencariannya .woodpecker/*.yaml atau .yml, lalu .woodpecker.yaml, lalu .woodpecker.yml. Kalau memakai folder .woodpecker/, setiap berkas di dalamnya jadi workflow terpisah yang berjalan paralel, dan depends_on memakai nama berkas tanpa path, tanpa titik di depan, dan tanpa ekstensi.
  • Commit bisa dilewati dengan [CI SKIP] atau [SKIP CI] di pesan commit, tidak peka huruf besar-kecil.
  • Workspace tidak dibagi antar workflow. File hanya bertahan di dalam satu workflow; untuk memindahkan artefak ke workflow deploy perlu plugin storage.
  • Uji dulu di laptop: woodpecker-cli exec .woodpecker.yaml menjalankan pipeline lokal, jadi kesalahan YAML ketahuan sebelum masuk repo.

Langkah 5: Secret, Izin, dan Bagian yang Berbahaya

CI yang jalan otomatis berarti kode orang lain ikut jalan di server kita. Di sinilah kesalahan paling mahal biasanya terjadi.

Secret punya tiga tingkat. Prioritasnya dari yang paling kuat: secret repo, secret organisasi, lalu secret global. Secret global hanya bisa dibuat admin instance dan berlaku untuk seluruh pipeline di mesin itu, jadi pakai seperlunya. Nilai secret diambil di pipeline lewat from_secret, bukan ditulis mentah di YAML:


steps:
  - name: deploy
    image: alpine
    commands:
      - echo "token: $TOKEN_ENV"
    environment:
      TOKEN_ENV:
        from_secret: deploy_token

Secret tidak dikirim ke pull request secara bawaan. Ini pengaman yang bagus, dan sebaiknya tidak diubah hanya karena satu pipeline butuh. Kalau repo kita menerima PR dari siapa saja, membukanya untuk event pull_request sama dengan memberi kunci ke semua orang yang bisa membuka PR.

Repo “trusted” memberi kekuatan yang jauh lebih besar. Hanya admin instance yang bisa menyalakannya, dan efeknya pipeline boleh memakai privileged, memasang volume host, mengubah network_mode, dan menerima kredensial git di setiap step. Dokumentasinya memberi peringatan tegas: siapa pun yang bisa mengubah konfigurasi pipeline di repo itu praktis bisa menguasai host tempat agent berjalan. Kalau repo menerima kontribusi dari luar, jangan dinyalakan.

Bedakan plugin dari step biasa. Sebuah step hanya dianggap plugin kalau tidak mendefinisikan commands, entrypoint, maupun environment. Kalau salah satunya diisi, step itu kehilangan hak istimewa plugin, termasuk akses ke secret yang dibatasi per image. Ini penting saat kita memfilter secret berdasarkan image: filternya hanya berlaku untuk step yang benar-benar plugin.

Kredensial git hanya diberikan ke step clone dan plugin tepercaya. Woodpecker membuat kredensial git dari akun forge, dan kredensial itu bisa dipakai untuk push ke repo. Yang menerimanya cuma step clone bawaan, plugin di daftar WOODPECKER_PLUGINS_TRUSTED_CLONE, dan semua step di repo yang ditandai trusted. Jadi daftar putih itu jangan diisi plugin sembarangan dari PR orang lain.

Kalau Build Tetap Gagal: Enam Pemeriksaan Cepat

Enam hal berikut yang paling sering memakan waktu saat pemasangan pertama.

  1. Webhook tidak pernah masuk. Gejalanya repo aktif tapi tidak ada pipeline baru. Periksa ALLOWED_HOST_LIST di app.ini Forgejo, lalu lihat riwayat webhook di halaman repo Forgejo. Kalau tertulis host tidak diizinkan, penyebabnya bukan Woodpecker.
  2. Clone gagal dengan pesan could not read Username for 'https://...'. Kredensial git hanya diberikan ke step clone dan plugin yang ada di daftar trusted clone, jadi mengganti image clone dengan image buatan sendiri langsung memutus akses ke repo privat. Untuk Forgejo yang dilaporkan lewat URL internal, samakan nama jaringan di WOODPECKER_BACKEND_DOCKER_NETWORK dengan jaringan Forgejo, atau pakai gateway docker0 (biasanya 172.17.0.1). Kalau repo publik tetap menuntut login, set WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=true.
  3. Agent tidak muncul di daftar. Cocokkan WOODPECKER_AGENT_SECRET di kedua kontainer. Kalau berbeda satu huruf, agent gagal mendaftar dan tidak pernah muncul di daftar, sementara server tetap jalan normal tanpa gejala lain. Secret yang panjang lebih aman disimpan di berkas dan dibaca lewat WOODPECKER_AGENT_SECRET_FILE.
  4. Build jalan tapi langsung mati di step pertama. Biasanya masalahnya ada di agent yang tidak bisa mengakses socket Docker, bukan di isi pipeline. Di host dengan SELinux aktif (Alma, Rocky, Fedora), tambahkan opsi :z pada mount /var/run/docker.sock.
  5. Step yang sama jalan bersamaan di repo yang sama. Ini biasanya karena WOODPECKER_MAX_WORKFLOWS dinaikkan tanpa memikirkan batas CPU. Bawaannya 1, artinya satu workflow per agent. Menaikkannya jadi 4 di VPS 2 vCPU hanya membuat semuanya saling memperlambat.
  6. Login berputar balik ke Forgejo. Hampir selalu Redirect URI yang tidak sama persis. Periksa skema, hostname, dan path /authorize, termasuk ada tidaknya garis miring di akhir.

Kesimpulan

Pipeline mandiri bukan soal gengsi, tapi soal siapa yang memegang kunci build kita. Dengan Woodpecker, Forgejo tetap menjadi sumber kebenaran untuk repo dan izin, sementara build berjalan di mesin yang kita kendalikan sendiri. Dua hal yang paling menentukan keberhasilan pemasangan ini justru kecil: loopback di ALLOWED_HOST_LIST Forgejo, dan nama jaringan Docker yang sama untuk server, agent, dan Forgejo.

Sisanya soal kebiasaan. Jangan nyalakan trusted tanpa alasan, jangan bagikan secret ke pull request, dan uji YAML di laptop dengan woodpecker-cli exec sebelum push. Kalau sudah terbiasa, menambah satu tes otomatis terasa seperti menambah satu baris konfigurasi, bukan proyek baru. Selamat mencoba, dan semoga pipeline pertamanya hijau tanpa perlu begadang.

Baca juga

Nevacloud VPS Indonesia

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *