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如果要删除这些文件，则必须直接进入部署分支以删除它们。这是为了防止部署脚本的意外更改创建破坏变化。
