gh action pypi publish
v1.12.2
Tindakan ini memungkinkan Anda mengunggah paket distribusi Python Anda di direktori dist/ ke PyPI. Teks ini menyarankan ikhtisar penggunaan minimalis. Untuk panduan lebih rinci, lihat panduan PyPA.
Jika Anda memiliki masukan mengenai versi tindakan tertentu, silakan tinggalkan komentar di diskusi pengumuman per rilis yang sesuai.
master Versi cabang master telah terbenam. Harap ubah versi Tindakan GitHub yang Anda gunakan dari master menjadi release/v1 atau gunakan tag yang tepat, atau ikut serta untuk menggunakan Git commit penuh SHA dan Dependabot.
Catatan
Penerbitan tepercaya tidak dapat digunakan dari dalam alur kerja yang dapat digunakan kembali saat ini. Disarankan untuk membuat alur kerja yang tidak dapat digunakan kembali yang berisi pekerjaan yang memanggil alur kerja Anda yang dapat digunakan kembali, dan kemudian melakukan langkah penerbitan tepercaya dari pekerjaan terpisah dalam alur kerja yang tidak dapat digunakan kembali tersebut. Alternatifnya, Anda masih bisa menggunakan nama pengguna/token di dalam alur kerja yang dapat digunakan kembali.
Catatan
Penerbitan tepercaya terkadang disebut dengan teknologi yang mendasarinya -- OpenID Connect, atau disingkat OIDC. Jika Anda melihat referensi ke "penerbitan OIDC" dalam konteks PyPI, inilah yang dimaksud.
Contoh ini langsung merujuk pada praktik terbaik saat ini. Jika Anda ingin menggunakan token API secara langsung atau nama pengguna dan kata sandi yang kurang aman, lihat cara menentukan nama pengguna dan kata sandi.
Tindakan ini mendukung implementasi penerbitan tepercaya PyPI, yang memungkinkan autentikasi ke PyPI tanpa token API yang dikonfigurasi secara manual atau kombinasi nama pengguna/kata sandi. Untuk melakukan penerbitan tepercaya dengan tindakan ini, penerbit proyek Anda harus sudah dikonfigurasi di PyPI.
Untuk memasuki alur penerbitan tepercaya, konfigurasikan tugas tindakan ini dengan izin id-token: write dan tanpa nama pengguna atau kata sandi eksplisit:
# .github/workflows/ci-cd.ymljobs: pypi-publish:name: Unggah rilis ke PyPIruns-on: ubuntu-latestenvironment: name: pypi url: https://pypi.org/p/<your-pypi-project -nama>izin: id-token: tulis # PENTING: izin ini wajib untuk penerbitan tepercayalangkah-langkah:# ambil distribusi Anda di sini- nama: Publikasikan distribusi paket ke Penggunaan PyPI: pypa/gh-action-pypi-publish@release/v1
Catatan
Kiat pro: daripada menggunakan penunjuk cabang, seperti unstable/v1 , sematkan versi Actions yang Anda gunakan untuk menandai versi atau pengidentifikasi penerapan sha1. Hal ini akan membuat alur kerja Anda lebih aman dan dapat direproduksi dengan lebih baik, sehingga menyelamatkan Anda dari kejutan yang tiba-tiba dan tidak menyenangkan.
Indeks lain yang mendukung penerbitan tepercaya juga dapat digunakan, seperti TestPyPI:
- nama: Publikasikan distribusi paket ke TestPyPI kegunaan: pypa/gh-action-pypi-publish@release/v1 dengan: url-repositori: https://test.pypi.org/legacy/
(jangan lupa perbarui nama lingkungan menjadi testpypi atau serupa!)
Catatan
Kiat pro: hanya atur izin id-token: write pada pekerjaan yang melakukan penerbitan, bukan secara global. Selain itu, coba pisahkan pembuatan dan penerbitan — hal ini memastikan bahwa skrip apa pun yang dimasukkan secara jahat ke dalam lingkungan pembuatan atau pengujian tidak akan dapat meningkatkan hak istimewa saat tidak terdeteksi radar.
Kasus penggunaan yang umum adalah mengunggah paket hanya pada komit yang diberi tag, untuk melakukannya tambahkan filter ke pekerjaan:
jika: github.event_name == 'push' && startWith(github.ref, 'refs/tags')
Penting
Dukungan untuk menghasilkan dan mengunggah pengesahan digital saat ini masih bersifat eksperimental dan terbatas hanya pada alur Penerbitan Tepercaya menggunakan PyPI atau TestPyPI. Dukungan untuk fitur ini belum stabil; pengaturan dan perilaku yang dijelaskan di bawah ini dapat berubah tanpa pemberitahuan sebelumnya.
Catatan
Membuat dan mengunggah pengesahan digital saat ini memerlukan autentikasi dengan penerbit tepercaya.
Membuat pengesahan digital yang ditandatangani untuk semua file distribusi dan mengunggah semuanya kini diaktifkan secara default untuk semua proyek yang menggunakan Penerbitan Tepercaya. Untuk menonaktifkannya, atur attestations sebagai berikut:
dengan: pengesahan: salah
Objek pengesahan dibuat menggunakan Sigstore untuk setiap paket distribusi, menandatanganinya dengan identitas yang disediakan oleh token OIDC GitHub yang terkait dengan alur kerja saat ini. Ini berarti autentikasi penerbitan tepercaya dan pengesahan terkait dengan identitas yang sama.
Tindakan GitHub ini tidak ada hubungannya dengan pembuatan distribusi paket . Pengguna bertanggung jawab menyiapkan dist untuk diunggah dengan memasukkannya ke dalam folder dist/ sebelum menjalankan Tindakan ini.
Penting
Karena GitHub Action ini berbasis docker, maka hanya dapat digunakan dari dalam pekerjaan berbasis GNU/Linux di alur kerja GitHub Actions CI/CD. Hal ini memang disengaja dan sepertinya tidak akan berubah karena sejumlah pertimbangan yang kami andalkan.
Namun hal ini tidak boleh menghentikan seseorang untuk menerbitkan paket distribusi khusus platform. Sangat disarankan untuk memisahkan pekerjaan untuk membuat roda khusus OS dari pekerjaan penerbitan. Hal ini memungkinkan seseorang untuk (1) menguji artefak yang sama persis yang akan diunggah ke PyPI, (2) mencegah pekerjaan paralel yang tidak disinkronkan menerbitkan hanya sebagian dari dist secara asinkron (dalam kasus ketika sebagian dari pekerjaan gagal dan yang lain berhasil berakhir) dengan rilis yang tidak lengkap di PyPI) dan (3) membuat unggahan atom ke PyPI (ketika bagian dari dist muncul di PyPI, penginstal seperti pip akan menggunakan versi tersebut untuk resolusi ketergantungan tetapi hal ini dapat menyebabkan beberapa lingkungan gunakan sdists sementara roda untuk runtime mereka belum tersedia).
Untuk menerapkan orkestrasi semacam ini, silakan gunakan actions/upload-artifact dan actions/download-artifact untuk berbagi perbedaan yang dibuat di seluruh tahapan dan pekerjaan. Kemudian, gunakan pengaturan needs untuk mengurutkan tahapan build, test, dan publishing.
Untuk hasil terbaik, cari tahu jenis alur kerja yang sesuai dengan kebutuhan spesifik proyek Anda.
Misalnya, Anda dapat menerapkan pekerjaan paralel yang mendorong setiap penerapan ke TestPyPI atau server indeks Anda sendiri, seperti devpi . Untuk melakukan ini, Anda perlu (1) menentukan nilai repository-url khusus dan (2) membuat nomor versi unik untuk setiap unggahan sehingga tidak menimbulkan konflik. Yang terakhir ini dimungkinkan jika Anda menggunakan paket setuptools_scm tetapi Anda juga bisa menemukan solusi Anda sendiri berdasarkan jarak ke komit yang diberi tag terbaru.
Anda harus membuat token lain untuk host terpisah dan kemudian menyimpannya sebagai rahasia repo GitHub di lingkungan yang digunakan dalam pekerjaan Anda. Padahal, memasukkan kata sandi akan menonaktifkan penerbitan tepercaya tanpa rahasia, jadi lebih baik mengonfigurasinya, saat menerbitkan ke TestPyPI dan bukan sesuatu yang khusus.
Pemanggilan tindakan dalam kasus ini akan terlihat seperti:
- nama: Publikasikan paket ke TestPyPI
kegunaan: pypa/gh-action-pypi-publish@release/v1
dengan: kata sandi: ${{ rahasia.TEST_PYPI_API_TOKEN }}url-repositori: https://test.pypi.org/legacy/ Anda dapat mengubah direktori target default dist/ ke direktori mana pun yang Anda sukai. Pemanggilan tindakan sekarang akan terlihat seperti:
- nama: Publikasikan paket ke PyPI kegunaan: pypa/gh-action-pypi-publish@release/v1 dengan: paket-dir: dir-kustom/
Direkomendasikan agar Anda menjalankan twine check tepat setelah memproduksi file Anda, namun ini juga menjalankan twine check sebelum diunggah. Anda juga dapat menonaktifkan pemeriksaan benang dengan:
dengan: verifikasi-metadata: false
Terkadang, saat Anda memublikasikan rilis dari beberapa tempat, alur kerja Anda mungkin mengalami kondisi balapan. Misalnya, saat memublikasikan dari beberapa CI atau bahkan memiliki alur kerja dengan langkah-langkah yang sama yang dipicu dalam CI/CD Tindakan GitHub untuk peristiwa berbeda mengenai tindakan tingkat tinggi yang sama.
Untuk memfasilitasi kasus penggunaan ini, Anda dapat menggunakan pengaturan skip-existing (dinonaktifkan secara default) sebagai berikut:
dengan: lewati yang ada: benar
Catatan
Kiat pro: cobalah untuk menghindari mengaktifkan pengaturan ini jika memungkinkan. Jika Anda memiliki langkah-langkah untuk memublikasikan ke PyPI dan TestPyPI, pertimbangkan hanya menggunakannya untuk yang terakhir, karena yang pertama akan gagal dalam duplikatnya.
Terkadang, twine upload bisa gagal dan untuk melakukan debug gunakan pengaturan verbose sebagai berikut:
dengan: verbose: benar
Anda mungkin ingin memverifikasi apakah file di PyPI diunggah secara otomatis oleh skrip CI. Ini akan menampilkan nilai SHA256, MD5, BLAKE2-256 dari file yang akan diunggah.
dengan:print-hash: benar
Nilai nama pengguna default adalah __token__ . Jika Anda memublikasikan ke registri khusus yang tidak menyediakan token API, seperti devpi , Anda mungkin perlu menentukan pasangan nama pengguna dan kata sandi khusus. Ini adalah bagaimana hal itu dilakukan.
dengan:pengguna: guidopassword: ${{ rahasia.DEVPI_PASSWORD }} Rahasia yang digunakan dalam ${{ secrets.DEVPI_PASSWORD }} perlu dibuat di halaman lingkungan di bawah pengaturan proyek Anda di GitHub. Lihat Membuat & menggunakan rahasia.
Di masa lalu, saat memublikasikan ke PyPI, cara paling aman untuk pelingkupan akses untuk penerbitan otomatis adalah dengan menggunakan fitur token API PyPI. Seseorang akan menjadikannya cakupan proyek dan menyimpannya sebagai rahasia yang terikat lingkungan dalam pengaturan repositori GitHub mereka, menamakannya ${{ secrets.PYPI_API_TOKEN }} , misalnya. Lihat Membuat & menggunakan rahasia. Meskipun masih aman, penerbitan tepercaya kini dianjurkan melalui token API sebagai praktik terbaik pada platform yang didukung (seperti GitHub).
Dockerfile dan skrip serta dokumentasi terkait dalam proyek ini dirilis di bawah lisensi 3-klausul BSD.
