1.1.6 • Published 7 months ago
ziyi-micro-framework v1.1.6
Github Actions
ci 的流程和解释如下所示：
# 当前的 yml（.yaml） 文件是一个 workflow，必须放置在项目的 .github/workflow 目录下
# name: 当前 workflow 的名称
name: ci
# on: 指定 workflow 触发的 event
#
# event 有以下几种类型
# - webhook
# - scheduled
# - manual
on:
# push: 一个 webhook event，用于提交代码时触发 workflow，也可以是触发列表，例如 [push, pull_request]
# workflows 触发的 event 大部分是基于 webhook 配置，以下列举几个常见的 webhook:
# - delete: 删除一个 branch 或 tag 时触发
# - fork / watch: 某人 fork / watch 项目时触发（你问有什么用，发送邮件通知不香吗？）
# - pull_request: 提交 PR 时触发
# - page_build: 提交 Github Pages-enabled 分支代码时触发
# - push: 提交代码到特定分支时触发
# - registry_package: 发布或跟新 package 时触发
# 更多 webhook 可查看 https://docs.github.com/zh/actions/using-workflows/events-that-trigger-workflows
# 从这里可以看出 Git Actions 的一大特点就是 Gihub 官方提供的一系列 webhook
push:
# branches: 指定 push 触发的特定分支，这里你可以通过列表的形式指定多个分支
branches:
- demo/**
- feat/**
- fix/**
#
# branches 的指定可以是通配符类型，例如以下配置可以匹配 refs/heads/releases/10
# - 'releases/**'
#
# branches 也可以使用反向匹配，例如以下不会匹配 refs/heads/releases/10
# - '!releases/**'
#
# branches-ignore: 用于指定当前 webhook 不触发的分支
#
# tags: 用于指定当前 webhook 触发的 tag
#
# tags:
# - v1 # Push events to v1 tag
# - v1.* # Push events to v1.0, v1.1, and v1.9 tags
#
# tags-ignore: 类似于 branches-ignore
#
# paths、paths-ignore...
#
# 更多关于特定过滤模式可查看 https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
#
# 其他的 webhook 控制项还包括 types（不是所有的 webhook 都有 types），例如已 issues 为例，可以在 issues 被 open、reopened、closed 等情况下触发 workflow
# 更多 webhook 的 types 可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows#webhook-events
#
# on:
# issues:
# types: [opened, edited, closed]
# 除此之外如果对于每个分支有不同的 webhook 触发，则可以通过以下形式进行多个 webhook 配置
#
# push:
# branches:
# - master
# pull_request:
# branches:
# - dev
#
# 除了以上所说的 webhook event，还有 scheduled event 和 manual event
# scheduled event: 用于定时构建，例如最小的时间间隔是 5 min 构建一次
# 具体可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events
# env: 指定所有 job 和 step 通用的环境变量（在 job 中或者 steps 中也可以通过 env 配置自己的环境变量）
#
# defaults: 当前所有 job 的默认配置
# jobs: 一个 workflow 由一个或多个 job 组成
jobs:
# job id: 是 job 的唯一标识，可以通过 _ 进行连接，例如: my_first_job，例如这里的 test 就是一个 job id
test:
# name: 在 Github 中显示的 job 名称
name: CI 执行流程
#
# needs: 用于继发执行 job，例如当前 job build 必须在 job1 和 job2 都执行成功的基础上执行
# jobs:
# job1:
# job2:
# needs: job1
# job3:
# needs: [job1, job2]
#
# runs-on: job 运行的环境配置，包括:
# - windows-latest
# - windows-2019
# - ubuntu-20.04
# - ubuntu-latest
# - ubuntu-18.04
# - ubuntu-16.04
# - macos-latest
# - macos-10.15
# - self-hosted（本地机器，具体可查看 https://docs.github.com/zh/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow）
runs-on: ubuntu-latest
#
# outputs: 用于输出信息
#
# env: 用于设置当前 job 的环境变量
#
# defaults: 当前所有 step 的默认配置
# if: 满足条件执行当前 job
# steps: 一个 job 由多个 step 组成，step 可以
# - 执行一系列 tasks
# - 执行命令
# - 执行 action
# - 执行公共的 repository
# - 在 Docker registry 中的 action
steps:
#
# id: 类似于 job id
#
# if: 类似于 job if
#
# name: 当前 step 的名字
- name: 下载 Github 仓库
#
# uses: 用于执行 action
#
# action: 可以重复使用的单元代码
# - 为了 workflow 的安全和稳定建议指定 action 的发布版本或 commit SHA
# - 使用指定 action 的 major 版本，这样可以允许你接收 fixs 以及 安全补丁并同时保持兼容性
# - 尽量不建议使用 master 版本，因为 master 很有可能会被发布新的 major 版本从而破坏了 action 的兼容性
# - action 可能是 JavaScript 文件或 Docker 容器，如果是 Docker 容器，那么 runs-on 必须指定 Linux 环境
#
# 指定固定 commit SHA
# uses: actions/setup-node@74bc508
# 指定一个 major 发布版本
# uses: actions/setup-node@v1
# 指定一个 minor 发布版本
# uses: actions/setup-node@v1.2
# 指定一个分支
# uses: actions/setup-node@master
# 指定一个 Github 仓库子目录的特定分支、ref 或 SHA
# uses: actions/aws/ec2@master
# 指定当前仓库所在 workflows 的目录地址
# uses: ./.github/actions/my-action
# 指定在 Dock Hub 发布的 Docker 镜像地址
# uses: docker://alpine: 3.8
# A Docker image in a public registry
# uses: docker:/gcr.io/cloud-builders/gradle
# checkout action 主要用于向 github 仓库拉取源代码（需要注意 workflow 是运行在服务器上，因此需要向远程的 github 拉取仓库源代码）
# 它的功能包括但不限于
# - Fetch all history for all tags and branches
# - Checkout a different branch
# - Checkout HEAD^
# - Checkout multiple repos (side by side)
# - Checkout multiple repos (nested)
# - Checkout multiple repos (private)
# - Checkout pull request HEAD commit instead of merge commit
# - Checkout pull request on closed event
# - Push a commit using the built-in token
# checkout action: https: //github.com/actions/checkout
uses: actions/checkout@v4
# with: action 提供的输入参数
# with:
# 指定 checkout 的分支、tag 或 SHA
# 如果默认不指定，则指向触发工作流所在分支的 SHA
# When checking out the repository that triggered a workflow, this defaults to the reference or SHA for that event.
# 更多 checkout action 的配置可查看 https://github.com/actions/checkout#usage
# ref: feat/ci
#
# run: 使用当前的操作系统的默认的 non-login shell 执行命令行程序
# 运行单个脚本
# run: npm install
# 运行多个脚本
# run: |
# npm ci
# npm run build
#
# working-directory: 用于指定当前脚本运行的目录
# working-directory: ./temp
#
# shell: 可以指定 shell 类型进行执行，例如 bash、pwsh、python、sh、cmd、powershell
# shell: bash
#
# env: 除了可以设置 workflow 以及 job 的 env，也可以设置 step 的 env（可以理解为作用域不同，局部作用域的优先级更高）
#
# comtinue-on-error: 默认当前 step 失败则会阻止当前 job 继续执行，设置 true 时当前 step 失败则可以跳过当前 job 的执行
# - name: 缓存 node_modules 依赖
# # cache action: https://github.com/actions/cache
# # cache 在这里主要用于缓存 npm，提升构建速率
# uses: actions/cache@v3
# # npm 缓存的路径可查看 https://docs.npmjs.com/cli/cache#cache
# # 由于这里 runs-on 是 ubuntu-latest，因此配置 ~/.npm
# with:
# # 指定缓存和还原的路径
# path: ~/.npm
# # key 中定义缓存标志，runner.os 指当前环境的系统。
# # 这里使用 package-lock.json 的内容生成 Hash 值作为缓存的 key 值
# # 一旦 package-lock.json 发生变化，则会导致 Hash 值变化，从而变更缓存内容
# key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
# # 备用 key，如果 key 没有命中缓存，则可以使用 restore-keys 进行备用缓存匹配
# restore-keys: |
# ${{ runner.os }}-node-
# github-script action: https://github.com/actions/github-script
# 在 workflow 中使用 Script 语法调用 Github API 或引用 workflow context
# - uses: actions/github-script@v6
# id: my-script
# with:
# result-encoding: string
# retries: 3
# script: |
# github.rest.issues.get({
# issue_number: context.issue.number,
# owner: context.repo.owner,
# repo: context.repo.repo,
# })
# setup-node action: https://github.com/actions/setup-node
# 配置 Node 执行环境（当前构建的服务器默认没有 Node 环境，可以通过 Action 安装 Node）
# 需要注意安装 Node 的同时会捆绑安装 npm，如果想了解为什么会捆绑，可以 Google 一下有趣的故事哦
# 因此使用了该 action 后就可以使用 npm 的脚本在服务器进行执行啦
- name: 下载和安装 Node 环境
uses: actions/setup-node@v3
with:
# 在 package.json 的 engines 中我们配置了 "node": ">=16.18.1"
# 因此这里对安装的 Node 进行版本限定
node-version: "16.x"
- name: 安装依赖
# 需要注意 npm ci 和 npm i 的区别
run: npm ci
- name: 代码校验
run: npm run lint
- name: 单元测试
run: npm test
- name: 文档构建
run: npm run docs:build
- name: 代码构建
run: npm run build
#
# timeout-minutes: 一个 job 执行的最大时间，默认是 6h，如果超过时间则取消执行
#
# strategy.matrix: 例如指定当前 job 的 node 版本列表、操作系统类型列表等
# strategy.fail-fast
# strategy.max-parallel
# continue-on-error: 一旦当前 job 执行失败，那么 workflow 停止执行。设置为 true 可以跳过当前 job 执行
# container: Docker 容器配置，包括 image、env、ports、volumes、options 等配置
#
# services: 使用 Docker 容器 Action 或者 服务 Action 必须使用 Linux 环境运行