Mendistribusikan skrip Anda sendiri lewat Homebrew

 (justin.searls.co)
9 poin oleh GN⁺ 2025-09-18 | 2 komentar | Bagikan ke WhatsApp
  • Homebrew adalah package manager di macOS yang memudahkan instalasi dan pengelolaan alat CLI, sehingga developer dapat menyiapkan lingkungan sistem secara efisien dengan alat yang sering mereka gunakan
  • Panduan ini menjelaskan proses mendistribusikan skrip CLI pribadi dengan Homebrew, serta menunjukkan cara menyederhanakan pemeliharaan melalui integrasi GitHub dan alur kerja otomatis
  • Proses distribusinya mengikuti alur membuat CLI → rilis GitHub → membuat Tap → menulis dan memperbarui Formula, dan pada akhirnya dapat diinstal hanya dengan perintah brew tap dan brew install
  • Dengan memahami sistem istilah dan best practice Homebrew, Anda dapat melakukan distribusi yang stabil dengan reproduktibilitas dan keamanan rantai pasok yang lebih kuat
  • Ini juga dapat diotomatisasi melalui workflow GitHub Actions, dan setelah sekali disiapkan, distribusi CLI lain berikutnya menjadi jauh lebih mudah

Latar belakang dan motivasi

  • Homebrew adalah package manager pilihan untuk menginstal alat CLI dan digunakan oleh banyak developer
  • Namun, banyak orang mendistribusikan CLI buatan mereka sendiri lewat npm atau RubyGem, sehingga cara distribusi via Homebrew bisa terasa asing
  • Repositori core resmi Homebrew memiliki kebijakan bahwa tim Homebrew enggan menerima pendaftaran alat buatan sendiri, sehingga developer umum mendistribusikannya lewat tap dan formula terpisah
  • Panduan ini dijelaskan berdasarkan pengalaman mendistribusikan CLI sederhana berbasis Ruby

Penjelasan istilah

  • Homebrew menggunakan istilah khas yang mengikuti tema pembuatan bir, jadi memahaminya akan memudahkan Anda menangkap struktur sistemnya
    • Formula adalah file definisi paket yang berisi instruksi untuk menginstal source code atau biner
    • Tap adalah repositori Git untuk kumpulan Formula, digunakan untuk mengelola paket kustom per pengguna atau organisasi
    • Cask adalah manifest instalasi untuk aplikasi GUI atau biner berukuran besar, mirip Formula tetapi menangani file yang sudah dibangun sebelumnya
    • Bottle adalah bentuk paket biner prebuilt yang disalin tanpa membangun dari source, sehingga mempercepat instalasi
    • Cellar adalah direktori tempat Formula yang sudah terinstal disimpan, misalnya pada path /opt/homebrew/Cellar
    • Keg adalah direktori instance instalasi untuk Formula tertentu, ditempatkan per versi di dalam Cellar

Gambaran umum

  • Repositori core Homebrew tidak menerima konten yang terlalu niche atau bersifat pribadi, sehingga pengguna harus membuat repositori tap terpisah untuk mendistribusikan CLI mereka
    • 1. Buat CLI, unggah ke GitHub, lalu buat rilis bertag
    • 2. Buat Tap dengan brew tap-new, lalu push ke GitHub
    • 3. Tulis Formula dengan brew create (termasuk URL tarball dan SHA256)
    • 4. Setiap ada rilis versi baru, perbarui Formula agar pengguna dapat menginstalnya dengan mudah lewat perintah brew install
  • Setelah distribusi selesai, pengguna dapat menginstal CLI hanya dengan dua perintah: brew tap your_github_handle/tap dan brew install your_cool_cli
    • Panduan ini tidak membahas pengembangan CLI, dan berfokus pada pembuatan tap, pembuatan Formula, serta proses pembaruan
    • Sebagai contoh, digunakan CLI imsg yang membuat arsip web interaktif dari database iMessage

Membuat tap

  • Ikuti panduan pembuatan tap Homebrew, lalu sesuaikan dengan nama pengguna atau organisasi GitHub Anda
    • Untuk mengumpulkan semua alat CLI ke dalam satu tap di masa mendatang, nama homebrew-tap direkomendasikan; awalan homebrew diperlakukan khusus oleh CLI dan awalan tap adalah konvensi umum
  • Jalankan perintah pembuatan tap: brew tap-new searlsco/homebrew-tap
    • Ini akan membuat scaffold di /opt/homebrew/Library/Taps/searlsco/homebrew-tap
    • Buat repositori pasangannya di GitHub, lalu push hasil yang telah dibuat: cd /opt/homebrew/Library/Taps/searlsco/homebrew-tap, git remote add origin git@github.com:searlsco/homebrew-tap.git, git push -u origin main
  • Setelah memiliki tap tersebut, pengguna lain bisa meng-clone repositorinya ke /opt/homebrew/Library/Taps dengan perintah brew tap searlsco/tap
    • Pada awalnya belum ada isi yang berguna, tetapi perilaku dasarnya bisa dipastikan berjalan

Membuat Formula

  • Homebrew bisa langsung merujuk ke repositori GitHub, tetapi menyarankan penggunaan tarball berversi dan checksum untuk memperkuat reproduktibilitas serta keamanan rantai pasok open source
  • Perintah untuk membuat Formula: brew create https://github.com/searlsco/imsg/archive/refs/tags/v0.0.5.tar.gz --tap searlsco/homebrew-tap --set-name imsg --ruby
    • Flag --tap menentukan tap kustom dan menempatkan Formula di /opt/homebrew/Library/Taps/searlsco/homebrew-tap/Formula
    • --set-name imsg menetapkan nama Formula secara eksplisit; pilih nama yang unik untuk menghindari duplikasi (misalnya, hati-hati agar tidak bentrok dengan CLI TLDR atau standard yang sudah ada)
    • --ruby adalah preset template untuk Ruby CLI, salah satu dari beberapa opsi yang menyederhanakan kustomisasi
  • Formula yang dihasilkan mungkin belum langsung berfungsi, jadi gunakan LLM untuk memperbaikinya: jalankan brew install --verbose imsg, lalu masukkan error ke ChatGPT dan ulangi pembaruan Formula
    • File akhir Formula/imsg.rb dapat disalin sebagai titik awal untuk distribusi Ruby CLI
    • Dengan mendistribusikannya lewat Homebrew alih-alih package manager spesifik bahasa, upgrade di sisi pengguna tetap lancar meskipun bahasa implementasinya berubah

Sorotan utama Formula

  • Semua Formula ditulis dalam Ruby, karena sebelum JavaScript atau AI populer, banyak alat pengembang ditulis berbasis Ruby
    • Metode head dapat digunakan untuk menentukan repositori Git, tetapi efek nyatanya tidak jelas
    • Menambahkan livecheck bernilai karena memudahkan pembaruan versi Formula
    • Pengujian eksekusi biner bisa diimplementasikan secara sederhana dengan memeriksa output bantuan; jangan terintimidasi oleh komentar yang dihasilkan otomatis
    • Gunakan perintah brew style searlsco/tap untuk memeriksa error gaya
    • Default uses_from_macos "ruby" pada template --ruby memakai versi 2.6.10 (rilis sebelum COVID, EOL 3 tahun lalu), sehingga disarankan bergantung pada Formula ruby terbaru dengan depends_on "ruby@3"
  • Jika Formula sudah memuaskan, lakukan git push untuk distribusi langsung, dan pengguna dapat menginstalnya dengan brew tap searlsco/tap serta brew install imsg

Memperbarui Formula untuk setiap rilis CLI

  • url dan hash sha256 di bagian atas Formula harus diperbarui manual pada setiap rilis, dan ini merepotkan; bahkan membuat tag push atau GitHub release pun terasa melelahkan
    • Perintah bump-formula-pr milik Homebrew atau GitHub Actions bisa membuat PR, tetapi proses fork dan PR terasa tidak perlu rumit
    • Jika Anda pemilik tap, pendekatan yang lebih diinginkan adalah cara sederhana yang langsung commit ke branch main
  • Untuk menghindari itu, disarankan menambahkan workflow GitHub ke repositori Formula agar tap diperbarui otomatis saat rilis
    • Anda dapat menyalin dan menggunakan contoh workflow
    • Konfigurasi yang diperlukan: saat membuat GitHub personal access token (PAT), beri izin Content → Write pada repositori homebrew-tap, lalu simpan di Secrets repositori Formula sebagai HOMEBREW_TAP_TOKEN
    • Tentukan tap dan Formula melalui environment variable (misalnya, baris 13-15)
    • Disarankan memperbarui akun bot GitHub: GH_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com, GH_NAME: github-actions[bot]
  • Setelah rilis dibuat dan git push --tags dijalankan, pembaruan otomatis akan terjadi dalam beberapa detik, dan pengguna dapat melakukan upgrade dengan brew update serta brew upgrade imsg

Bagian terbaiknya

  • Proses ini memang rumit, tetapi setelah pengaturan tap dan satu contoh Formula selesai, distribusi CLI tambahan menjadi nyaris sepele
    • Sangat praktis karena Formula baru bisa dipublikasikan hanya dalam beberapa menit
  • Proses resmi Homebrew memang agak kompleks, tetapi otomatisasi membuatnya lebih nyaman
    • Ini mengurangi kerepotan antara rilis dan distribusi tiap alat, serta dapat diperluas untuk mendukung CLI dari berbagai bahasa
  • Belum tentu akan benar-benar menerbitkan Formula lain lagi, tetapi menyenangkan mengetahui kemungkinannya terbuka

Bacaan terkait

2 komentar

 
lamanus 2025-09-18

PR dapat dibuat dengan perintah bump-formula-pr Homebrew atau GitHub Actions, tetapi proses fork dan PR menjadi rumit tanpa perlu

Tersedia opsi --no-fork sehingga Anda bisa langsung push branch dan melakukan merge, serta menyediakan fitur pembaruan otomatis.
 
GN⁺ 2025-09-18
Opini Hacker News

  • Aturan penamaan Homebrew kadang terasa membingungkan, tetapi secara keseluruhan saya terus merasa ini benar-benar alat yang sangat berguna
    Saya juga tidak menyangka proses membuat tap sendiri untuk mendistribusikan tool bisa sesederhana ini
    Dibandingkan package manager per bahasa (misalnya uv), saya penasaran apa kelebihannya
    Secara khusus, saya ingin tahu apakah ini lebih mudah bagi orang yang tidak berada di dalam ekosistem tertentu, yaitu apakah unggul dari sudut pandang keumuman

    • Terima kasih, alat lain yang memakai package registry umumnya memerlukan pembuatan akun, autentikasi dua faktor, proses penandatanganan, dan sebagainya
      Homebrew jauh lebih sederhana secara keseluruhan karena ketentuan layanan GitHub (ToS) berperan sebagai dasar kepercayaan
      Tim Homebrew juga bisa mengurangi banyak kerumitan berkat pendekatan ini

    • Jika bicara berdasarkan paket Python, upaya untuk memaketkan semuanya sekaligus seperti uv secara realistis cukup sulit
      Karena itu, biasanya yang dipakai adalah pendekatan menginstal hanya dependensi yang dikunci di lingkungan venv
      Sebagai contoh konkret, lihat formula ini
      Soal uv, saya sempat mencoba mendukung paket privat dengan tool resmi (brew update-python-resources, homebrew-pypi-poet), tetapi tidak berjalan dengan baik
      Jadi saya membuat sendiri uvbrew untuk membantu pembuatan resource
      Ada juga dokumentasi resmi untuk referensi menulis formula Python di Homebrew

  • Jika Anda pengembang Go, saya merekomendasikan tool Goreleaser
    Ini membuat distribusi biner di dalam tap pribadi menjadi sangat mudah (cara ini dilarang di core resmi)

    • Baru-baru ini saya tahu bahwa Goreleaser sekarang mendukung bukan hanya Go, tetapi juga Rust, TypeScript, Python, Zig, dan banyak bahasa lain
      Ini sangat berguna dalam pengelolaan proyek lintas bahasa

  • Secara pribadi, saya pikir lebih ideal jika pembaruan dikelola langsung dari sisi tap
    Umumnya mirip dengan cara upstream melakukan pembaruan
    Jika melihat workflow ini, formula/cask yang tidak Anda miliki pun bisa diperbarui dengan mudah
    Dengan perintah brew bump, Anda bisa memindai semuanya, membuat PR, lalu mengotomatiskan pengujian dengan brew test-bot
    Contoh PR nyata bisa dilihat di sini

    • Menurut saya ini ide yang bagus
      Biasanya saya enggan mencobanya karena merasa sayang dengan waktu penggunaan GitHub Actions, tetapi karena gratis untuk open source, pemakaian seperti ini tampaknya masuk akal

  • Saya pernah menulis sendiri homebrew-bump-revision, workflow otomatis untuk bump versi di Homebrew tap saya
    Saya memakainya dengan baik di beberapa proyek pribadi

    • Kelihatannya keren
      Saya tidak mencobanya karena malas, tetapi ini tool yang bagus

  • Ada episode di podcast Ruby Rogues yang membahas berbagai tips saat mendistribusikan CLI dengan Homebrew
    Anda bisa mendengar lebih banyak lewat tautan episode terkait

  • Saya menemukan hal yang menarik soal packaging tool Python
    Beberapa paket Python dapat menimbulkan loop dependensi selama proses build sehingga tidak kompatibel dengan Homebrew
    pip tidak bermasalah karena mengunduh rilis biner, tetapi Homebrew membangun sendiri semua dependensi, sehingga prosesnya jauh lebih lama
    Akibatnya, proyek Python berukuran sedang pun bisa memerlukan lebih dari satu jam untuk build "bottle"

  • Sejak mulai memakai nix untuk administrasi sistem, saya tidak pernah menyesalinya sedikit pun
    Satu-satunya hal yang agak disayangkan hanyalah bahwa saya tetap harus bergantung pada Windows karena game multipemain