github pages deploy action
v4.7.2
Secara otomatis menggunakan proyek Anda ke halaman GitHub dengan tindakan GitHub. Tindakan ini dapat dikonfigurasi untuk mendorong kode siap-produksi Anda ke cabang mana pun yang Anda inginkan, termasuk halaman GH dan dokumen . Ini juga dapat menangani penyebaran repositori silang dan juga berfungsi dengan perusahaan GitHub.
Pemeliharaan proyek ini dimungkinkan oleh semua kontributor dan sponsor. Jika Anda ingin mensponsori proyek ini dan membuat logo Avatar atau Perusahaan Anda muncul di bawah klik di sini. ?
Anda dapat memasukkan tindakan dalam alur kerja Anda untuk memicu pada peristiwa apa pun yang didukung oleh tindakan GitHub. Jika cabang jarak jauh yang ingin Anda gunakan belum ada, tindakan akan membuatnya untuk Anda. Alur kerja Anda juga perlu menyertakan langkah actions/checkout sebelum alur kerja ini berjalan agar penyebaran berfungsi. Jika Anda bermaksud membuat beberapa penyebaran secara berurutan, Anda mungkin perlu memanfaatkan parameter konkurensi dalam alur kerja Anda untuk mencegah tumpang tindih.
Anda dapat melihat contoh di bawah ini.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build-and-deploy :
concurrency : ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build # The folder the action should deploy. Catatan
Anda harus mengonfigurasi repositori Anda untuk menyebarkan dari cabang yang Anda dorong. Untuk melakukan ini, buka pengaturan repositori Anda, klik Pages , dan pilih Deploy from a Branch dari dropdown Source . Dari sana pilih cabang yang Anda berikan untuk tindakan tersebut. Dalam kebanyakan kasus ini akan menjadi gh-pages karena itu default.
Jika Anda ingin membuatnya sehingga alur kerja hanya memicu acara dorong ke cabang tertentu maka Anda dapat memodifikasi bagian on .
on :
push :
branches :
- main Peringatan
Jika Anda tidak menyediakan tindakan dengan token akses atau kunci SSH, Anda harus mengakses pengaturan repositori Anda dan memberikan Read and Write Permissions kepada GITHUB_TOKEN yang disediakan, jika tidak, Anda akan berpotensi mengalami masalah izin. Atau Anda dapat mengatur yang berikut dalam file alur kerja Anda untuk memberikan tindakan izin yang dibutuhkan.
permissions :
contents : write with porsi alur kerja harus dikonfigurasi sebelum tindakan akan berhasil. Anda dapat menambahkan ini di bagian with yang ditemukan dalam contoh di atas. secrets apa pun harus direferensikan menggunakan sintaks braket dan disimpan di menu Settings/Secrets Github Repository. Anda dapat mempelajari lebih lanjut tentang pengaturan variabel lingkungan dengan tindakan github di sini.
Opsi berikut harus dikonfigurasi untuk membuat penyebaran.
| Kunci | Informasi nilai | Jenis | Diperlukan |
|---|---|---|---|
folder | Folder di repositori Anda yang ingin Anda gunakan. Jika skrip build Anda dikompilasi menjadi direktori bernama build , Anda akan meletakkannya di sini. Jika Anda ingin menggunakan direktori root, Anda dapat menempatkan a . Di Sini. Anda juga dapat menggunakan jalur file absolut dengan prepending ~ ke jalur folder Anda. Perhatikan bahwa setiap file/folder yang cocok dengan entri .gitignore tidak akan digunakan. Beberapa alat menghasilkan file .gitignore untuk output build. | with | Ya |
Secara default, tindakan tidak memerlukan konfigurasi token apa pun dan menggunakan token github yang disediakan untuk membuat penyebaran. Jika Anda memerlukan lebih banyak kustomisasi, Anda dapat memodifikasi jenis penempatan menggunakan opsi berikut.
| Kunci | Informasi nilai | Jenis | Diperlukan |
|---|---|---|---|
token | Opsi ini default ke Token GitHub Repositori ScoPed. Namun, jika Anda membutuhkan lebih banyak izin untuk hal -hal seperti menggunakan repositori lain, Anda dapat menambahkan token akses pribadi (PAT) di sini. Ini harus disimpan dalam secrets / with menu sebagai rahasia . Kami merekomendasikan menggunakan akun layanan dengan izin paling sedikit yang diperlukan dan merekomendasikan saat menghasilkan PAT baru yang Anda pilih dengan izin paling sedikit yang diperlukan. Pelajari lebih lanjut tentang membuat dan menggunakan rahasia terenkripsi di sini. | with | TIDAK |
ssh-key | Anda dapat mengonfigurasi tindakan untuk digunakan menggunakan SSH dengan mengatur opsi ini ke kunci SSH pribadi yang disimpan sebagai rahasia . Ini juga dapat diatur ke true untuk menggunakan konfigurasi klien SSH yang ada. Untuk informasi lebih rinci tentang cara menambahkan pasangan kunci SSH publik/pribadi Anda, silakan merujuk ke bagian Kunci Deploy dari ReadMe ini. | with | TIDAK |
| Kunci | Informasi nilai | Jenis | Diperlukan |
|---|---|---|---|
branch | Ini adalah cabang yang ingin Anda sebutkan, misalnya, gh-pages atau docs . Default ke gh-pages . | with | TIDAK |
git-config-name | Memungkinkan Anda untuk menyesuaikan nama yang dilampirkan ke konfigurasi git yang digunakan saat mendorong penempatan berkomitmen. Jika ini tidak termasuk itu akan menggunakan nama dalam konteks GitHub, diikuti dengan nama tindakan. | with | TIDAK |
git-config-email | Memungkinkan Anda untuk menyesuaikan email yang dilampirkan ke konfigurasi git yang digunakan saat mendorong penempatan berkomitmen. Jika ini tidak termasuk, itu akan menggunakan email dalam konteks GitHub, diikuti oleh email noreply GitHub generik. Anda dapat memasukkan <> untuk nilai jika Anda ingin menghilangkan bidang ini sama sekali dan mendorong komit tanpa email. | with | TIDAK |
repository-name | Memungkinkan Anda untuk menentukan jalur repositori yang berbeda selama Anda memiliki izin untuk mendorongnya. Ini harus diformat seperti SO: JamesIves/github-pages-deploy-action . Anda harus menggunakan PAT di input token untuk opsi konfigurasi ini agar berfungsi dengan baik. | with | TIDAK |
target-folder | Jika Anda ingin mendorong konten folder penyebaran ke direktori tertentu pada cabang penyebaran, Anda dapat menentukannya di sini. | with | TIDAK |
commit-message | Jika Anda perlu menyesuaikan pesan komit untuk integrasi, Anda dapat melakukannya. | with | TIDAK |
clean | Anda dapat menggunakan opsi ini untuk menghapus file dari tujuan penyebaran Anda yang tidak ada lagi di sumber penyebaran Anda. Salah satu kasus penggunaan adalah jika proyek Anda menghasilkan file hash yang bervariasi dari build ke build. Menggunakan clean tidak akan mempengaruhi direktori .git , .github , atau .ssh . Opsi ini dihidupkan secara default dan dapat ditimbulkan dengan mengaturnya menjadi false . | with | TIDAK |
clean-exclude | Jika Anda perlu menggunakan clean tetapi Anda ingin menyimpan file atau folder tertentu, Anda dapat menggunakan opsi ini. Ini harus berisi setiap pola sebagai satu baris dalam string multiline. | with | TIDAK |
dry-run | Jangan benar-benar mendorong kembali, tetapi gunakan --dry-run pada doa git push sebagai gantinya. | with | TIDAK |
single-commit | Opsi ini dapat diaktifkan ke true jika Anda lebih suka memiliki satu komit di cabang penyebaran daripada mempertahankan riwayat penuh. Menggunakan opsi ini juga akan menyebabkan riwayat yang ada dihapus dari cabang penyebaran . | with | TIDAK |
force | Penyebaran baru-berduyun-buatan untuk menimpa versi sebelumnya; Kalau tidak, cobalah untuk merebut kembali penyebaran baru ke yang sudah ada. Opsi ini dihidupkan secara default dan dapat ditimbulkan dengan mengaturnya menjadi false , yang mungkin berguna jika ada beberapa penyebaran dalam satu cabang. | with | TIDAK |
attempt-limit | Berapa banyak upaya rebase untuk dilakukan sebelum menangguhkan pekerjaan. Opsi ini default ke 3 dan mungkin berguna untuk meningkat ketika ada beberapa penyebaran dalam satu cabang. | with | TIDAK |
silent | Membungkam output tindakan yang mencegahnya menampilkan pesan git. | with | TIDAK |
tag | Tambahkan tag ke komit. Hanya berfungsi ketika dry-run tidak digunakan. | with | TIDAK |
Dengan tindakan yang dikonfigurasi dengan benar, Anda akan melihat alur kerja memicu penyebaran di bawah kondisi yang dikonfigurasi.
Tindakan ini akan mengekspor variabel lingkungan yang disebut deployment_status yang dapat Anda gunakan dalam alur kerja Anda untuk menentukan apakah penyebaran berhasil atau tidak. Anda dapat menemukan penjelasan dari setiap jenis status di bawah ini.
| Status | Keterangan |
|---|---|
success | Status success menunjukkan bahwa tindakan tersebut dapat berhasil digunakan ke cabang. |
failed | Status failed menunjukkan bahwa tindakan mengalami kesalahan saat mencoba menggunakan. |
skipped | Status skipped menunjukkan bahwa tindakan keluar lebih awal karena tidak ada hal baru untuk digunakan. |
Nilai ini juga ditetapkan sebagai output langkah sebagai deployment-status .
Jika Anda lebih suka menggunakan tombol Deploy SSH sebagai lawan dari token, Anda harus terlebih dahulu menghasilkan kunci SSH baru dengan menjalankan perintah terminal berikut, mengganti email dengan yang terhubung ke akun GitHub Anda.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " Setelah Anda menghasilkan pasangan kunci, Anda harus menambahkan konten kunci publik dalam menu Deploy Keys Repositori Anda. Anda dapat menemukan opsi ini dengan pergi ke Settings > Deploy Keys , Anda dapat memberi nama kunci publik apa pun yang Anda inginkan, tetapi Anda perlu memberikannya akses menulis. Setelah itu, tambahkan konten kunci pribadi ke menu Settings > Secrets sebagai DEPLOY_KEY .
Dengan ini dikonfigurasi, Anda kemudian dapat mengatur bagian ssh-key dari tindakan ke kunci pribadi Anda yang disimpan sebagai rahasia.
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : site
ssh-key : ${{ secrets.DEPLOY_KEY }} name : Build and Deploy
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txt
ssh-key : ${{ secrets.DEPLOY_KEY }} Atau, jika Anda sudah mengkonfigurasi klien SSH dalam langkah sebelumnya, Anda dapat mengatur opsi ssh-key untuk true untuk mengizinkannya menggunakan menggunakan klien SSH yang ada. Alih -alih menyesuaikan konfigurasi klien, itu hanya akan beralih ke menggunakan titik akhir SSH GitHub.
Tindakan ini terutama dikembangkan menggunakan Ubuntu. Dalam konfigurasi pekerjaan alur kerja Anda, disarankan untuk mengatur properti runs-on ke ubuntu-latest .
jobs :
build-and-deploy :
runs-on : ubuntu-latest Jika Anda menggunakan sistem operasi seperti Windows, Anda dapat mengatasinya menggunakan artefak. Dalam konfigurasi alur kerja Anda, Anda dapat memanfaatkan actions/upload-artifact dan actions/download-artifact untuk memindahkan proyek Anda yang dibangun di atas pekerjaan Windows ke pekerjaan sekunder yang akan menangani penyebaran.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build :
runs-on : windows-latest # The first job utilizes windows-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Upload Artifacts ? # The project is then uploaded as an artifact named 'site'.
uses : actions/upload-artifact@v1
with :
name : site
path : build
deploy :
concurrency : ci-${{ github.ref }}
needs : [build] # The second job must depend on the first one to complete before running and uses ubuntu-latest instead of windows.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Download Artifacts ? # The built project is downloaded into the 'site' folder.
uses : actions/download-artifact@v1
with :
name : site
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : ' site ' # The deployment folder should match the name of the artifact. Even though our project builds into the 'build' folder the artifact name of 'site' must be placed here. Jika Anda menggunakan wadah dalam alur kerja Anda, Anda mungkin perlu menjalankan langkah tambahan untuk menginstal rsync karena tindakan ini tergantung padanya. Anda dapat melihat contoh di bawah ini.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 Jika Anda menggunakan domain khusus dan memerlukan file CNAME , atau jika Anda memerlukan penggunaan file .nojekyll , Anda dapat dengan aman melakukan file -file ini langsung ke cabang penyebaran tanpa mereka diganti setelah setiap penyebaran, tambahan, Anda dapat memasukkan file -file ini dalam folder penyebaran Anda untuk memperbarui. Jika Anda perlu menambahkan file tambahan ke penyebaran yang harus diabaikan oleh langkah pembersihan build, Anda dapat menggunakan opsi clean-exclude .
name : Build and Deploy
permissions :
contents : write
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txtJika Anda ingin menghapus file -file ini, Anda harus masuk ke cabang penyebaran secara langsung untuk menghapusnya. Ini untuk mencegah perubahan yang tidak disengaja dalam skrip penyebaran Anda dari membuat perubahan yang melanggar.
