Publikasikan tindakan GitHub kustom

Selesai

Di sini, Anda akan mempelajari tentang memilih visibilitas yang tepat untuk tindakan Anda, praktik terbaik untuk mendokumentasikan dan membuat versi tindakan Anda, dan cara menerbitkan tindakan Anda ke GitHub Marketplace.

Pilih lokasi untuk tindakan Anda

Saat membuat tindakan, penting untuk terlebih dahulu memutuskan di mana Anda ingin tindakan tersebut hidup dan visibilitas tindakan tersebut, apakah itu akan public atau private. Visibilitas tindakan menentukan rekomendasi dan persyaratan mana yang diperlukan untuk merilis tindakan tersebut. Mari kita lihat lebih dekat ke dua opsi visibilitas ini.

Publik

Alur kerja di repositori apa pun dapat menggunakan tindakan publik. Jika Anda mengembangkan tindakan dengan niat untuk membuatnya sumber terbuka atau membuatnya tersedia untuk umum melalui GitHub Marketplace, kami sarankan (dan dalam banyak kasus diperlukan) bahwa tindakan tersebut memiliki repositorinya sendiri alih-alih menggabungkannya dengan kode aplikasi lain. Ini memungkinkan Anda untuk membuat versi, melacak, dan merilis tindakan seperti perangkat lunak lainnya. Ini memudahkan komunitas GitHub untuk menemukan tindakan, mempersempit cakupan basis kode untuk pengembang memperbaiki masalah dan memperluas tindakan, dan memisahkan penerapan versi tindakan dari penerapan versi kode aplikasi lainnya.

Privat

Saat tindakan berada di repositori privat, hanya alur kerja di repositori yang sama yang dapat menggunakan tindakan tersebut. Dengan tindakan privat, Anda dapat menyimpan file tindakan di lokasi mana pun di repositori Anda. Jika Anda berencana untuk menggabungkan tindakan, alur kerja, dan kode aplikasi dalam satu repositori, sebaiknya simpan tindakan di .github direktori. Misalnya, .github/actions/action-a dan .github/actions/action-b.

Mendokumentasikan tindakan Anda

Sangat membuat frustrasi untuk menggunakan alat atau aplikasi baru ketika dokumentasi tidak jelas atau bahkan hilang. Penting untuk menyertakan dokumentasi yang baik dengan tindakan Anda sehingga orang lain dapat melihat cara kerjanya, apakah Anda berencana untuk menjadikannya publik atau privat. Hal pertama yang harus dilakukan adalah membuat file README.md yang baik untuk tindakan Anda.

File README.md sering kali merupakan tempat pertama yang akan dilihat pengembang untuk melihat cara kerja tindakan. Ini adalah tempat yang bagus untuk menyertakan semua informasi penting untuk tindakan tersebut. Berikut ini adalah daftar hal-hal yang tidak lengkap untuk disertakan:

• Deskripsi terperinci tentang apa yang dilakukan tindakan tersebut.
• Argumen input dan output yang diperlukan.
• Argumen input dan output opsional.
• Rahasia yang digunakan tindakan.
• Variabel lingkungan yang digunakan tindakan.
• Contoh cara menggunakan tindakan Anda dalam alur kerja.

Sebagai aturan umum, README.md file harus menyertakan semua yang harus diketahui pengguna untuk menggunakan tindakan. Jika Anda berpikir itu bisa menjadi informasi yang berguna, sertakan dalam README.md.

Merilis dan membuat versi tindakan Anda

Jika Anda mengembangkan tindakan untuk digunakan orang lain, baik itu publik atau privat, Anda harus menentukan strategi manajemen rilis untuk mengontrol bagaimana pembaruan didistribusikan. Pembaruan versi utama termasuk perbaikan penting yang diperlukan dan patch keamanan yang memengaruhi kompatibilitas perlu didokumentasikan dengan jelas.

Praktik yang baik untuk rilis dan manajemen versi

Strategi manajemen rilis yang baik harus mencakup rekomendasi penerapan versi. Pengguna tidak boleh mereferensikan cabang default tindakan dengan tindakan tersebut. Ini karena cabang default yang kemungkinan berisi kode terbaru (yang mungkin atau mungkin tidak stabil) dapat mengakibatkan pemecahan alur kerja Anda. Sebagai gantinya, sebaiknya pengguna menentukan versi utama saat menggunakan tindakan, dan hanya mengarahkannya ke versi yang lebih spesifik jika mereka mengalami masalah. Mereka dapat melakukan ini dengan mengonfigurasi alur kerja GitHub Actions mereka untuk menargetkan tag, SHA penerapan, atau cabang tertentu bernama untuk rilis. Mari kita lihat lebih dekat cara kerja aturan ini.

Tag

Tag dapat menjadi cara yang baik untuk mengelola rilis untuk tindakan. Dengan menggunakan tag, pengguna dapat dengan mudah membedakan antara versi utama dan minor. Berikut ini adalah daftar praktik bermanfaat yang perlu dipertimbangkan saat membuat rilis:

• Buat dan validasi rilis pada cabang rilis (seperti release/v1) sebelum membuat tag rilis (misalnya, v1.0.2).
• Gunakan penerapan versi semantik.
• Pindahkan tag versi utama (seperti v1, v2) untuk menunjuk ke ref Git dari rilis saat ini.
• Memperkenalkan tag versi utama baru (v2) untuk perubahan yang akan merusak alur kerja yang ada.
• Rilis versi utama dengan tag beta untuk menunjukkan statusnya; misalnya, v2-beta. Anda dapat menghapus -beta tag saat rilis siap.

Berikut adalah beberapa contoh OKR.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

Menggunakan SHA penerapan

Tag berguna dan banyak digunakan, tetapi satu kelemahan untuk menggunakan tag adalah tag tersebut dapat dihapus atau dipindahkan. Dengan Git, setiap penerapan menerima nilai SHA terhitung, yang unik dan tidak dapat dimodifikasi. Menggunakan SHA penerapan untuk penerapan versi akan memberi Anda cara yang paling andal dan aman untuk membuat versi dan menggunakan tindakan. Namun, seringkali di Git Anda dapat singkatan hash SHA ke beberapa karakter pertama, dan Git akan mengenali referensi. Jika Anda menggunakan SHA penerapan untuk manajemen rilis, Anda perlu menggunakan nilai SHA lengkap dan bukan nilai singkatan.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Menerbitkan tindakan ke GitHub Marketplace

Saat siap membagikan tindakan dengan komunitas GitHub, Anda dapat menerbitkannya ke GitHub Marketplace dan menjangkau jutaan pengguna GitHub. Tindakan yang diterbitkan ke GitHub Marketplace segera diterbitkan jika semua persyaratan terpenuhi. Tindakan yang tidak memenuhi persyaratan perlu ditinjau oleh GitHub sebelum diterbitkan. Anda harus memastikan bahwa repositori hanya menyertakan file metadata, kode, dan file yang diperlukan untuk tindakan tersebut. Membuat satu repositori untuk tindakan memungkinkan Anda untuk menandai, merilis, dan mengemas kode dalam satu unit. GitHub juga menggunakan metadata tindakan di halaman GitHub Marketplace Anda.

Berikut ini adalah persyaratan untuk menerbitkan tindakan ke GitHub Marketplace. Ini berlaku untuk tindakan berbasis kontainer Docker dan tindakan berbasis JavaScript:

• Tindakan harus berada di repositori publik.
• Setiap repositori harus berisi satu tindakan.
• File metadata tindakan (action.yml atau action.yaml) harus berada di direktori akar repositori.
• file name metadata dalam tindakan harus unik di GitHub Marketplace.
  • Nama tidak dapat cocok dengan pengguna atau organisasi di GitHub, kecuali pengguna atau pemilik organisasi menerbitkan tindakan. Misalnya, hanya organisasi GitHub yang dapat menerbitkan tindakan bernama github.
  • name Tidak dapat mencocokkan kategori GitHub Marketplace yang ada.
  • name Tidak dapat mencocokkan fitur GitHub yang ada.

Anda dapat menambahkan tindakan yang telah Anda buat ke GitHub Marketplace dengan menandainya sebagai rilis baru lalu menerbitkannya. Ada beberapa langkah terpandu di GitHub yang memungkinkan Anda menerbitkan rilis tindakan Anda. Anda dapat menemukan informasi selengkapnya tentang langkah-langkah ini di bagian Ringkasan di akhir modul ini.