github pages deploy action
v4.7.2
自動將您的項目部署到使用GitHub操作的GitHub頁面上。可以將此操作配置為將您的生產準備代碼推入您想要的任何分支，包括GH頁面和文檔。它還可以處理跨存儲庫的部署，並與GitHub Enterprise合作。
所有貢獻者和讚助商都可以維護該項目。如果您想贊助此項目，並將您的頭像或公司徽標顯示在下面，請單擊此處。 ？
您可以在工作流程中包含操作，以在GitHub Actions支持的任何事件中觸發。如果您希望部署到的遠程分支尚不存在，則操作將為您創建。您的工作流程還需要在此工作流程運行之前包含actions/checkout步驟，以便部署工作。如果您打算快速連續地進行多個部署，則可能需要利用工作流程中的並發參數以防止重疊。
您可以在下面查看一個示例。
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. 筆記
您必須配置存儲庫以從推送到的分支部署。為此，請轉到您的存儲庫設置，單擊Pages ，然後從Source下拉列表中選擇Deploy from a Branch 。從那裡選擇您提供給操作的分支。在大多數情況下，這將是gh-pages因為這是默認值。
如果您想將其做到這一點，以便僅在推動事件上觸發特定分支機構，則可以修改on部分。
on :
push :
branches :
- main 警告
如果您不提供訪問令牌或SSH密鑰的操作，則必須訪問存儲庫設置並為提供的GITHUB_TOKEN提供Read and Write Permissions ，否則您可能會遇到許可問題。另外，您可以在工作流文件中設置以下內容，以授予操作所需的權限。
permissions :
contents : write 在操作起作用之前，必須配置with工作流程的部分。您可以在上面的示例中找到with部分中添加這些部分。必須使用括號語法引用任何secrets ，並存儲在GitHub存儲庫的Settings/Secrets菜單中。您可以在此處使用GitHub操作了解有關設置環境變量的更多信息。
必須配置以下選項以進行部署。
| 鑰匙 | 價值信息 | 類型 | 必需的 |
|---|---|---|---|
folder | 您要部署的存儲庫中的文件夾。如果您的構建腳本將其編譯成名為build的目錄，則將其放在此處。如果您希望部署根目錄，則可以放置一個.這裡。您也可以通過將~預備到文件夾路徑來利用絕對文件路徑。請注意，將不會部署任何匹配的文件/文件夾.gitignore條目。一些工具自動生成a .gitignore文件以構建輸出。 | with | 是的 |
默認情況下，該操作不需要任何令牌配置，並且使用提供的存儲庫示波器github令牌來進行部署。如果需要更多自定義化，則可以使用以下選項修改部署類型。
| 鑰匙 | 價值信息 | 類型 | 必需的 |
|---|---|---|---|
token | 此選項默認為存儲庫範圍的github令牌。但是，如果您需要更多的權限，例如部署到另一個存儲庫，則可以在此處添加個人訪問令牌（PAT）。這應該存儲在secrets / with菜單中作為秘密。我們建議使用最少必要的權限的服務帳戶，並建議在生成新的PAT時選擇最少的許可範圍。在此處了解有關創建和使用加密秘密的更多信息。 | with | 不 |
ssh-key | 您可以通過將此選項設置為秘密存儲的私有SSH密鑰來配置使用SSH部署的操作。也可以將使用現有的SSH客戶端配置設置為true 。有關如何添加您的公共/私人SSH密鑰對的更多詳細信息，請參考使用此讀數的部署密鑰部分。 | with | 不 |
| 鑰匙 | 價值信息 | 類型 | 必需的 |
|---|---|---|---|
branch | 這是您希望部署到的分支機構，例如gh-pages或docs 。默認為gh-pages 。 | with | 不 |
git-config-name | 允許您自定義與GIT配置相關的名稱，該名稱在推動部署提交時使用。如果不包括其中，它將在github上下文中使用名稱，然後使用操作的名稱。 | with | 不 |
git-config-email | 允許您自定義與GIT配置相關的電子郵件，該電子郵件在推動部署提交時使用。如果不包括其中，它將在github上下文中使用電子郵件，然後使用通用的noreply github電子郵件。如果您想完全省略此字段，並在沒有電子郵件的情況下推動提交，則可以將其包括在內<> | with | 不 |
repository-name | 只要您擁有推動它的權限，就可以指定不同的存儲庫路徑。應該像這樣的格式化： JamesIves/github-pages-deploy-action 。您需要在token輸入中使用此配置選項的PAT才能正常工作。 | with | 不 |
target-folder | 如果您想將部署文件夾的內容推入部署分支的特定目錄，則可以在此處指定。 | with | 不 |
commit-message | 如果您需要自定義集成的提交消息，則可以這樣做。 | with | 不 |
clean | 您可以使用此選項從部署源中不再存在的部署目標刪除文件。一種用例是，如果您的項目生成的Hashed文件因構建而異。使用clean不會影響.git ， .github或.ssh目錄。默認情況下，可以將此選項打開，可以通過將其設置為false來切換。 | with | 不 |
clean-exclude | 如果您需要使用clean ，但要保留某些文件或文件夾，則可以使用此選項。這應該包含每個模式作為多行字符串中的單行。 | with | 不 |
dry-run | 實際上不要向後推，而是使用 - 在git push調用中--dry-run 。 | with | 不 |
single-commit | 如果您希望在部署分支上有一個提交而不是維護完整的歷史記錄，則可以將此選項切換到true 。使用此選項還將導致任何現有歷史記錄都從部署分支中擦除。 | with | 不 |
force | 武力 - 武裝新部署以覆蓋先前的版本；否則，將嘗試將新部署反彈到任何現有的部署。默認情況下，可以將此選項打開，並且可以通過將其設置為false來切換，如果單個分支中有多個部署，這可能很有用。 | with | 不 |
attempt-limit | 在暫停工作之前，有多少個重新嘗試進行嘗試。此選項默認為3 ，並且在單個分支中有多個部署時可能會增加。 | with | 不 |
silent | 沉默的動作輸出阻止其顯示GIT消息。 | with | 不 |
tag | 在提交中添加標籤。僅在不使用dry-run時起作用。 | with | 不 |
通過正確配置的操作，您應該在配置的條件下看到工作流觸發部署。
該操作將導出一個稱為deployment_status的環境變量，您可以在工作流中使用，以確定部署是否成功。您可以找到以下每個狀態類型的說明。
| 地位 | 描述 |
|---|---|
success | success狀態表明該操作能夠成功部署到分支機構。 |
failed | failed狀態表明該操作在嘗試部署時遇到錯誤。 |
skipped | skipped狀態表明，該動作很早就退出了，因為沒有新的部署要部署。 |
該值也被設置為階躍輸出作為deployment-status 。
如果您希望使用SSH部署密鑰而不是代幣，則必須首先通過運行以下終端命令來生成新的SSH密鑰，並用連接到GitHub帳戶的電子郵件代替電子郵件。
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " "生成密鑰對後，必須在存儲庫的部署鍵菜單中添加公共密鑰的內容。您可以通過轉到Settings > Deploy Keys來找到此選項，無論您想要什麼，都可以將公共密鑰命名，但是您確實需要給它寫入訪問權限。之後，將私鑰的內容添加到Settings > Secrets菜單為DEPLOY_KEY 。
使用此配置，您可以將操作的ssh-key部分設置為“秘密”存儲的私鑰。
- 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 }}另外，如果您已經在上一步中配置了SSH客戶端，則可以將ssh-key選項設置為true ，以允許使用現有SSH客戶端部署它。它不會調整客戶端配置，而是只能切換到使用GitHub的SSH端點。
此操作主要是使用Ubuntu開發的。在您的工作流程配置中，建議將runs-on屬性設置為ubuntu-latest 。
jobs :
build-and-deploy :
runs-on : ubuntu-latest如果您使用的是Windows之類的操作系統，則可以使用工件解決此操作。在您的工作流程配置中，您可以利用actions/upload-artifact和actions/download-artifact操作將項目構建在Windows作業上的項目轉移到可以處理部署的輔助作業。
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.如果您在工作流程中使用容器，則可能需要運行一個額外的步驟來安裝rsync ，因為此操作取決於它。您可以在下面查看一個示例。
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4如果您使用的是自定義域並需要一個CNAME文件，或者需要使用.nojekyll文件，則可以將這些文件直接提交到部署分支中，而無需它們在每個部署之後被覆蓋，此外，您可以在部署文件夾中包含這些文件以更新它們。如果您需要將其他文件添加到部署中，這些文件應被構建清理步驟忽略，您可以使用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/*.txt如果要刪除這些文件，則必須直接進入部署分支以刪除它們。這是為了防止部署腳本的意外更改創建破壞變化。
