GitHub Actions 自动部署前端 Vue 项目

使用GitHub操作自动将项目部署到GitHub页面。这个动作可以配置为将production-ready代码推送到您想要的任何分支中，包括gh-pages和文档。它还可以处理跨存储库部署，并与GitHub Enterprise配合使用。

入门✈️

您可以在工作流中包含该操作，以便在GitHub操作支持的任何事件中触发。如果您希望部署到的远程分支不存在，则操作将为您创建它。您的工作流还需要在运行此工作流之前包含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@v3

      - 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.

如果您想使工作流只在推送事件到特定分支时触发，那么您可以修改on部分。

on:
  push:
    branches:
      - main

警告：如果您没有为该操作提供访问令牌或SSH密钥，则必须访问存储库设置并向提供的Read and Write Permissions提供GITHUB_TOKEN，否则可能会遇到权限问题。或者，您可以在工作流文件中设置以下内容，以授予操作所需的权限。

permissions:
  contents: write

Configuration

必须先配置工作流的with部分，然后操作才能工作。您可以在上述示例中找到的with部分中添加这些内容。必须使用括号语法引用任何secrets，并将其存储在GitHub存储库的Settings/Secrets菜单中。您可以在此处了解有关使用GitHub操作设置环境变量的更多信息。

Required Setup

为了进行部署，必须配置以下选项。

Key	Value Information	Type	Required
folder	存储库中要部署的文件夹。如果您的构建脚本编译到一个名为build的目录中，您可以将其放在这里。如果您希望部署根目录，可以在此处放置.。您还可以通过将~附加到文件夹路径来利用绝对文件路径。	with	Yes

默认情况下，该操作不需要任何令牌配置，并使用提供的存储库范围的GitHub令牌进行部署。如果需要更多自定义，可以使用以下选项修改部署类型。

Key	Value Information	Type	Required
token	此选项默认为存储库范围的GitHub令牌。但是，如果您需要更多权限来进行部署，例如部署到另一个存储库，则可以在此处添加个人访问令牌（PAT）。这应该作为秘密存储在secrets / with菜单中。我们建议使用所需权限最少的服务帐户，并建议在生成新PAT时选择所需权限最少的范围。在此了解有关创建和使用加密机密的更多信息。	with	No
ssh-key	通过将此选项设置为存储为机密的私有SSH密钥，可以配置要使用SSH部署的操作。还可以将其设置为true，以使用现有的SSH客户端配置。有关如何添加公共/私有ssh密钥对的更多详细信息，请参阅本自述文件的使用部署密钥部分。	with	No

Optional Choices

Key	Value Information	Type	Required
branch	这是您希望部署到的分支，例如gh-pages或docs。默认为gh-pages。	with	No
git-config-name	允许您自定义附加到git配置的名称，该配置在推动部署提交时使用。如果未包含此项，则将在GitHub上下文中使用名称，后跟操作的名称。	with	No
git-config-email	允许您自定义附加到git配置的电子邮件，在推动部署提交时使用git配置。如果未包含此内容，它将在GitHub上下文中使用电子邮件，然后是普通的noreply GitHub电子邮件。如果希望完全省略此字段并在不发送电子邮件的情况下推送提交，则可以在值中包含<>。	with	No
repository-name	允许您指定不同的存储库路径，只要您有推送权限。它的格式应该是：JamesIves/github-pages-deploy-action。您需要在token输入中使用PAT才能使这个配置选项正常工作。	with	No
target-folder	如果要将部署文件夹的内容推送到部署分支上的特定目录中，可以在此处指定。	with	No
commit-message	如果需要为集成自定义提交消息，可以这样做。	with	No
clean	您可以使用此选项从部署目标中删除部署源中不再存在的文件。一个用例是，如果您的项目生成的哈希文件因构建而异。使用clean不会影响.git、.github或.ssh目录。默认情况下，此选项处于打开状态，可以通过将其设置为false来关闭。	with	No
clean-exclude	如果你需要使用clean，但你想保留某些文件或文件夹，你可以使用这个选项。这应该将每个模式包含为多行字符串中的单行。	with	No
dry-run	实际上不要推回，而是在git push调用上使用–dry-run。	with	No
single-commit	如果您希望在部署分支上进行单个提交，而不是维护完整的历史记录，则可以将此选项切换为true。使用此选项还将导致从部署分支中删除任何现有历史记录。	with	No
force	Force-push覆盖以前版本的新部署；否则，尝试将新部署重新定位到任何现有部署上。默认情况下，此选项处于打开状态，可以通过将其设置为false来关闭，如果一个分支中有多个部署，这可能会很有用。	with	No
silent	使操作输出静音，防止其显示git消息。	with	No
workspace	这应该指向您的项目在虚拟机上的位置。GitHub Actions环境将为您设置这一点。只有在使用节点模块时才需要设置此变量。	with	No
tag	向提交添加标记。仅在未使用dry-run时有效。	with	No

正确配置操作后，您应该会看到工作流在配置的条件下触发部署。

Deployment Status

该操作将导出一个名为deployment_status的环境变量，您可以在工作流中使用该变量来确定部署是否成功。您可以在下面找到每种状态类型的解释。

Status	Description
success	success状态表示操作能够成功部署到分支。
failed	failed状态表示操作在尝试部署时遇到错误。
skipped	skipped状态表明，由于没有新的部署，操作很早就退出了。

该值也设置为步长输出deployment-status。

使用SSH部署密钥

如果您希望使用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 }}

You can view a full example of this here.

name: Build and Deploy
on:
  push:
    branches:
      - main
jobs:
  deploy:
    concurrency: ci-${{ github.ref }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout ️
        uses: actions/checkout@v3

      - 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作业构建的项目移动到将处理部署的辅助作业。

You can view an example of this pattern here.

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@v3

      - 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@v3

      - 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-up步骤应忽略的其他文件，可以使用clean-exclude选项。

Click here to view an example of this.

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@v3

      - 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

如果要删除这些文件，必须直接进入部署分支以删除它们。这是为了防止部署脚本中的意外更改创建破坏性更改。

转载自：github-pages-deploy-action: 使用GitHub操作自动将项目部署到GitHub页面。可以将此操作配置为将生产就绪代码推送到您想要的任何分支中。