（三）Jenkins 与 CI/CD | 在 GitHub 中发布静态网站

老实巴交的麻匪
139 阅读8分钟

系列文章：

（一）Jenkins 与 CI/CD | 容器化启动 Jenkins with docker in docker

（二）Jenkins 与 CI/CD | 基于 VitePress 快速搭建静态网站

（三）Jenkins 与 CI/CD | 在 GitHub 中发布静态网站

前言

第二篇文章介绍了使用 Docker 构建基于 VitePress 的静态资源站点。完成第二章的内容后，作者只能在开发环境中看到自己的“成果”，而无法让互联网上的用户访问。你或许已经访问过以 github.io 为域名后缀的网站，现在开始你也可以拥有。本文介绍利用 GitHub Workflows 在 GitHub 仓库中发布静态网站。

更令人惊喜的是，该流程原生支持了 CI/CD，所有的资源以及能力均由 GitHub 免费提供。

GitHub 真的是一个强大的网站，全球最大程序员交友网站！

介绍

在 GitHub 网站上工作流相关的概念包括：GitHub Workflow、GitHub Actions、GitHub Pages。

这三个概念不是并列关系，下面将做简要介绍。

GitHub Workflows 与 GitHub Actions

工作流是一个可配置的自动化过程，将运行一个或多个作业。工作流由签入到存储库的 YAML 文件定义，并将在存储库中的事件触发时运行，或者可以手动触发，或者按照定义的计划。

工作流在存储库的 .github/workflow 目录中定义。一个存储库可以有多个工作流，每个工作流都可以执行一组不同的任务，例如：

  • 构建和测试拉取请求
  • 每次创建版本时部署您的应用程序
  • 每当打开新问题时添加标签

工作流基础

工作流必须包含以下基本组件：

  1. 一个或多个将触发工作流的事件。
  2. 一个或多个作业，每个作业都将在运行机器上执行并运行一系列一个或多个步骤。
  3. 每个步骤都可以运行您定义的脚本或运行操作，这是一个可重用的扩展，可以简化您的工作流程。

有关这些基本组件的更多信息，请参阅了解 GitHub 操作

overview-action.png

GitHub Actions 是一个持续集成和持续交付（CI/CD）平台，允许您自动化构建、测试和部署管道。您可以创建工作流，以便在将更改推送到存储库时运行测试，或者将合并的拉取请求部署到生产环境。

用 GitHub Actions 来实现 GitHub Workflow 所规划出来的自动化流程。

GitHub Pages

You can use GitHub Pages to host a website about yourself, your organization, or your project directly from a repository on GitHub.

您可以使用 GitHub Pages 直接从 GitHub 上的存储库托管有关您自己、您的组织或您的项目的网站。GitHub Pages是一个静态站点托管服务，它直接从GitHub上的存储库获取超文本标记语言、CSS 和 JavaScript 文件，可选地通过构建过程运行文件，并发布网站。

GitHub Workflow 规划好自动化流程，GitHub Actions 充当这个流程的执行者。当涉及到 GitHub Pages 相关项目时，借助 GitHub Actions 编写的自动化流程，可以轻松搞定繁琐任务。例如，每次更新博客仓库的源码后，利用 Actions 设定的 Workflow，自动运行构建工具把 markdown 转成 HTML，再把生成的静态文件推送至 gh-pages 分支，触发 GitHub Pages 更新站点内容，全程无需手动干预，紧密串联起从代码更新到网页更新的链路。

静态站点发布

在开始本章节之前，请先阅读系列文章的前两篇。

项目构建概述：

  1. 创建 GitHub-Token，支持开发者模式访问 GitHub
  2. 创建并配置 github-actions.yaml，目录 .github/workflows/github-actions.yaml
  3. 在 GitHub 部署域名中添加项目名前缀 docker-vitepress

创建 GitHub Token

该过程在文章「（一）Jenkins 与 CI/CD | 容器化启动 Jenkins with docker in docker」有描述。

传送门：创建 GitHub Token

概述：

  1. 设置 Token 名，Note： MY_GITHUB_TOKEN（自定义名称，建议全大写）；
  2. 设置仓库权限；
  3. 生成 Token，请妥善保管（关闭后不可查看），将在下一小节用于登陆 GitHub。

github-token-scopes.png

Workflow 配置文件

在该项目的 GitHub 仓库 Settings 中配置仓库密钥

  1. Settings
  2. Security -> Secrets and variables -> Actions
  3. 创建新的仓库密钥： New repository secret
  4. 密钥命名为 VITE_TOKEN，密钥为上一小节中获取的一串 TOKEN

定义 workflow 配置文件，询问 ChatGPT、Kimi、豆包，或者 IDE 插件：腾讯云 AI 代码助手、Mars Code

基于 GitHub-Workflows 模板，定义配置文件 .github/workflows/github-actions.yaml。

name: VitePress-hope Github Deploy
on:
  # 1. 自动触发：当在 main 分支上执行 push 动作时
  push:
    branches:
      - main
  # 2. 手动触发
  workflow_dispatch:


jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        name: Install pnpm
        with:
          version: 9
          run_install: false

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install
      - name: Build
        run: pnpm run docs:build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          token: ${{secrets.VITE_TOKEN}}
          folder: docs/.vitepress/dist
          git-config-name: xiaolinstar
          git-config-email: xing.xiaolin@foxmail.com

在配置文件 38-40 行，设置个性化参数

  • token: ${{secrets.VITE_TOKEN}}
  • git-config-name: GitHub 用户名
  • git-config-email: GitHub 用户邮箱

当执行 git push 更新本 GitHub 仓库时，会自动触发 GitHub Actions；

workflow_dispatch 也支持点击按钮，手动触发。

添加域名前缀

GitHub Pages 发布和传统云服务器发布在域名上的区别：

GitHub Pages 发布方式比云服务器发布多了仓库名前缀，需要在项目部署时做区分和处理，以兼容这两类发布方式。

VitePress 项目的主要配置文件包括两个：

  • docs/index.md
  • docs/.vitepress/config.mts

只需在 config.mts 中添加 2 行代码即可区分项目部署方式。 修改后的config.mts内容如下（添加的代码已用注释标注）

import { defineConfig } from 'vitepress'

// @ts-ignore (*) 网站基础路径，区分GitHub部署和常规部署
const basePath = process.env.GITHUB_ACTIONS === 'true' ? '/docker-vitepress/' : '/'

// https://vitepress.dev/reference/site-config
export default defineConfig({
   base: basePath, // (*) 设置域名前缀
   title: "My Awesome Project",
   description: "A VitePress Site",
   themeConfig: {
      // https://vitepress.dev/reference/default-theme-config
      nav: [
         { text: 'Home', link: '/' },
         { text: 'Examples', link: '/markdown-examples' }
      ],

      sidebar: [
         {
            text: 'Examples',
            items: [
               { text: 'Markdown Examples', link: '/markdown-examples' },
               { text: 'Runtime API Examples', link: '/api-examples' }
            ]
         }
      ],

      socialLinks: [
         { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
      ]
   }
})

上述两小节均在本地开发，完成后推送到 GitHub 仓库。

启用 GitHub Pages

依据 github-acitons.yaml 配置文件， 触发 GitHub Actions 后，会在仓库生成 gh-pages 分支，将用于部署 GitHub Pages。

Actions 执行成功（下图为手动触发效果）：

actions-success.png

生成新的仓库分支 ph-pages：

GitHub gh-pages

在 GitHub Actions 中执行了构建的动作，但要发布为网页，需要启用 GitHub Pages。

下图展示，GitHub Pages 将 分支 gh-pages 发布。

pages.png

GitHub Pages 本质上也是一个 Actions 中的工作流，点击保存后，可以在 Actions 中看到一下执行动作：

pages build and deployment

workflows.png

站点发布完成后，即可输入域名查看效果：

pages-website.png

何以 CI/CD

静态资源网站没有后端数据库，对网站的维护是以源代码的形式进行的。优点是网站配置更新、修改非常灵活；缺点是以源代码的方式维护网站，需要一定的编程基础。

不过，编辑文章是通过编辑 Markdown 文件进行的，只要会使用 Markdown 来编辑文章，就可轻松驾驭网站维护。

网站维护工作流：

时序图是理想情况：每个步骤只执行一次且执行成功

sequenceDiagram
    本地 IDE ->> 本地 IDE: 项目维护：配置、文章编辑
    本地 IDE ->> 本地 IDE: 在开发环境查看更新效果
    本地 IDE ->> 本地 IDE: 预发布查看更新效果
    本地 IDE ->> GitHub 仓库: 推送变更到 GitHub 仓库
    GitHub 仓库 ->> GitHub 仓库: 执行 Workflows，项目重新构建
    GitHub 仓库 ->> 本地 IDE: 网站更新成功
    本地 IDE ->> 本地 IDE: 查看发布效果

网站维护

部署的网站如何维护呢？有了 CI/CD，该过程非常简单优雅，本小节做简单演示。

当前网站效果：

vitepress-awesome.png

下面进行网站信息维护，更新项目首页，使其展示中文信息。

修改 /docs/index.md 中的项目标题和描述，部分截取：

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
  name: "我的精彩项目"
  text: "一个 VitePress 网站"
  tagline: 微软是一家伟大的公司，是 GitHub 的拥有者
  actions:
    - theme: brand
      text: Markdown Examples
      link: /markdown-examples
    - theme: alt
      text: API Examples
      link: /api-examples

features:
  - title: Feature A
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
  - title: Feature B
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
  - title: Feature C
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
---

提交 git 版本，并推送到远程 GitHub 仓库，自动触发 workflow，网站更新。

all-workflowss.png

从发布到部署完成，整个过程作者只需一个 git push，发布耗时不到 2 分钟，就可以看到更新后到网站。

该项目公网访问地址：xiaolinstar.github.io/docker-vite…

vitepress-zh.png

总结

本文在部署 VitePress 静态网站的基础上，将项目通过 GitHub Pages 以生产发布。首先对 GitHub Workflows 等概念进行简单介绍，然后手把手实现 GitHub 仓库发布，最后演示了网站维护的方法，轻松实现最简单的 CI/CD。

本文中静态网站发布是依靠 GitHub 提供的能力，开发者对流程编排的能力并无太多参与。下一篇文章，将在云服务器上发布项目，并使用 Jenkins 体验设计 CI/CD 的流程，这将是一个里程碑，或者是 CI/CD 中的 Hello World。

关注微信公众号，获取运维资讯

如果此篇文章对你有所帮助，感谢你的点赞与收藏，也欢迎在评论区友好交流。

微信搜索关注公众号：持续运维

参考

  1. 关于 GitHub workflows docs.github.com/en/actions/…
  2. 了解 GitHub 操作 docs.github.com/en/actions/…
  3. 关于 GitHub Pages docs.github.com/en/pages/ge…
  4. 我的精彩网站 xiaolinstar.github.io/docker-vite…
  5. github-pages-deploy-action github.com/JamesIves/g…
avatar
文章
阅读
粉丝