github action 基于个人项目实践

前言: DevOps 和 Jenkins

作为一名开发，虽然也没有经常听到 Devops （研发和运维一体化）这个概念，但日常工作中已经无处不在地用着 DevOps 工具。自研也好，基于开源项目改造也好，互联网公司基本都会有自已的一套 DevOps 工具

所谓 DevOps 这个概念，不过是在我们日常开发流程上抽象一层，把开发、测试、运维等角色，日常的手动操作，都抽象成特定的语言/模板表述。有了这一层抽象之后，任务的自动化就有基础了。自动化之后 各个角色也能够从杂事中解放出来，分担其他角色的事情，或是更专注于领域深层的技术

一个完全没有实现自动化的研发体系，会是什么样的呢？想象一下：开发需要三头六臂，一边忙着开发需求，一边因为单元测试不够完善，不停地改着来自线上环境退回的 bug 单，甚至还要和运维 battle 服务部署的细节；测试一边要用 jmeter 给开发刚发布到测试环境的服务做压测，一边还要被测试组长批评: 这么基本的 bug 你怎么没有测出来？运维，那就更不用说了，这边数据库需要扩容，那边服务需要发布，根本没有停下休息的时候

光是想象一下就已经头大了。如果不依靠成熟的工具 去分担一些琐事，不管是什么角色，都无法专注自己应该做的事

于是我们要先说到 Jenkins: 一个开源的 CI/CD （持续集成、持续开发） 服务，对 DevOps 流程做了很好的抽象，上面说到的所有过程，在 Jenkins 中都变成了插件。不管你是开发 测试 还是运维，总能在插件市场中找到适合自己的，只需要按照既定的模板写好任务流程 ，就能自动化地执行任务了

举个例子，Go 这个插件，就可以帮你做好 golang 环境的初始化工作。你只需要把服务编译、打包指令写好就行，以后都可以用同一个模板
官方示例:

pipeline {
  // 选择任意执行机器
  agent any

  // 定义 golang 版本为 1.19，插件会自动帮我们在执行器中安装这个版本
  tools { go '1.19' }

  stages {
    stage('Build') {
      steps {
        // 打印 golang 版本
        sh 'go version'
        // 编译产生可执行文件
        sh 'go build -o main ./main.go'
      }
    }
  }
}

不过正是因为Jenkins对流程的抽象程度很高，上手难度也并不低。它的任务定义语法、插件系统、容器化部署、集群部署 ，每一块都可以深度展开。本文的重点并不是要深入介绍 Jenkins，也不是把目光放到公司级别: 几千上万人使用的DevOps工具是什么样子的，而是专注于我们自己，在自己项目的日常开发中，是否也能用上这样能给我们带来便利的工具呢？

笔者遇到的场景是，自己开发了一个服务镜像仓库（包含各种服务的 Dockerfile），以及一个后台服务。镜像更新了什么功能，需要在本地重新构建镜像提交到 docker hub 仓库；后台项目实现了新功能，想跑跑单元测试 验证完整性，也需要在本地手动执行所有单测方法。虽然说熟能生巧，但总归是需要自己去“亲力亲为”的事

正好，今天的主角 Github Action: 这样一个Github直接提供给我们的 自动化CI/CD 工具，就派上了用场。有了它，不管我的服务什么时候需要更新，我都只管把代码提交到 github，剩下的部署和测试过程，都交给 action 帮我执行就好，是真的 save my time 了

本文内容概览

本文将从 github action 的使用方式入手，介绍它的基本语法，了解如何从零开始构建 action 任务。然后从笔者个人的实践出发，探讨 action 是否真的可以帮助我们提升开发效率

github action

创建 action 任务

官方教程-Quickstart for GitHub Actions

Github Action 任务和 Github 代码仓库之间是绑定关系，一个 action 任务的描述文件最终会挂载到项目的 .github/workflows 目录下。我们可以在Github 上创建一个项目，然后按照官方文档的 quickstart 示例来提交一个 action 任务，就能体验基本功能了

这个任务不需要和仓库代码有任何关系，一个空项目都可以提交 action 任务

示例任务: （触发条件为 push 代表任意提交都会触发执行）

name: GitHub Actions Demo
run-name: ${{ github.actor }} is testing out GitHub Actions 
on: [push]
jobs:
  Explore-GitHub-Actions:
    runs-on: ubuntu-latest
    steps:
      # 打印一些 github action 自带的环境变量，如 github.event_name: 时间名称（push）、github.ref: 分支名（refs/heads/smiecj-patch-1）
      - run: echo " The job was automatically triggered by a ${{ github.event_name }} event."
      - run: echo " This job is now running on a ${{ runner.os }} server hosted by GitHub!"
      - run: echo " The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v3
      - run: echo " The ${{ github.repository }} repository has been cloned to the runner."
      - run: echo "️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}
      - run: echo " This job's status is ${{ job.status }}."

提交任务过程: 首先在仓库的 Action 一栏 创建一个自定义任务

然后会提示 是选择直接 commit 到主分支 还是创建一个单独分支 并创建 pr，这里建议选择后者

pr创建完成后，将自动触发 action 任务的执行，如下图 显示任务执行中

action 执行的每一个步骤（step）都有非常详细的日志

如果我们需要把刚才创建的 action 流程保存下来，可以把这个 pr 合并。也可以直接在本地开发时手动创建 .github/workflows 目录，将流程定义保存成 yml 文件 直接提交

基本概念

概念	说明
Workflow	任务单位，一个 github action yaml 文件即对应一个任务，一个 workflow 下 可定义多个 job
Event	触发 workflow 运行的事件，可以是一次 commit 提交，一次 pr 合并请求，到达设定的触发时间等
Job	Workflow 内定义的具体执行的任务，同一个 Workflow 中的任务将会在同一个 Runner 中运行，因此可以设定依赖关系，上一个 Job 的产物可以在下一个 Job 使用。默认没有依赖关系的 Job 将会并行执行
Action	将 Workflow 开放为模板，可在 Market 中供别人使用
Runner	Workflow 执行环境，每个 Runner 同时只能运行一个 job。若有特殊需求，可以使用更高性能的执行器，或者使用自己部署的执行器

Market

Github Action Market 类似刚才提到的 Jenkins Market，有非常多现成的，可以直接复用的任务。分类包括: 服务发布（如将服务发布到 aws）、安全（CodeQL 扫描）、持续集成（编译）、自动化（提交issue后自动回复）、页面生成（Hugo），非常丰富

Workflow 基本语法

About workflows

触发条件

对应基本概念中的 Action，常见配置有:

# 在提交到 main 分支时触发（PR 不会触发）
on:
  push:
    branches:
    - main
    - release/*

# 提交 合并到 main 分支的 PR 时触发
on:
  pull_request:
    branches:
    - main

# push / pr 且不论分支
on:
  [push, pull_request]

# 定时触发
# 注意: 触发时间为中时区 而不是当地时间 / crontab 表达式中最后一位的 day of the week 范围为 0-6
on:
  schedule:
    - cron:  '30 5,17 * * *'

更多触发条件

环境变量

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

常见默认环境变量，如 GITHUB_ACTOR 表示流程发起者

运行环境

对应概念的 Runner 执行器

jobs:
  my_job:
    name: deploy to staging
    runs-on: ubuntu-18.04

可选 Runner 列表

Linux 执行器的默认分配资源：2核7G 14G SSD – 基本够用了

初始化各语言环境

在Market中搜索关键字 actions/setup-语言名，大部分语言都有官方插件 支持初始化语言环境。比如如我们需要编译一个 java + maven 工程，就可以使用 actions/setup-java 插件，它会帮我们装好 java、maven、gradle 和 sbt 等环境

name: Java CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17' # 安装 Java 版本
          distribution: 'temurin' # 开源jdk 类型，可选 Zulu、Temurin 和 AdoptOpenJDK
      - name: Build with Maven
        # 通过 maven 编译项目
        run: mvn --batch-mode --update-snapshots package

产物

有一些action任务的执行结果 我们是希望 github 先帮我们保管的，比如服务编译后用于发布服务的安装包，或是测试报告等

# 上传
jobs:
  example-job:
    name: Save output
    steps:
      - shell: bash
        run: |
          expr 1 + 1 > output.log
      - name: Upload output file
        uses: actions/upload-artifact@v3
        with:
          name: output-log-file
          path: output.log

# 下载
jobs:
  example-job:
    steps:
      - name: Download a single artifact
        uses: actions/download-artifact@v3
        with:
          name: output-log-file

Workflow 的更多语法，如 构建过程缓存、引用其他项目的 workflow 可参考官方文档

限额

Usage limits, billing, and administration

既然是商用产品 免费使用的限额一定是有的，一部分限制如下:

• 单次 Job 的执行时间: 6小时
• Workflow 的执行时间: 35天
• 一小时内 请求 github api 次数: 1000次
• 同时运行的 job 数量: 20个（可以升级账号扩容），超过的将会排队

个人使用的话 同时运行 job 数 这个比较需要留意。不过避免超过限制的方式也简单: 不同任务的触发时间尽量错开，比如编译A服务设置在凌晨2点触发，编译B服务设置到凌晨3点

个人实践

掌握了 Github Action 的基本语法后，就可以基于具体的项目来实践了。笔者进行了镜像自动构建、单测覆盖率统计 两种任务的部署

镜像构建

之前做了一些开发环境镜像 和 大数据服务镜像 写成了 Dockerfile，都是在本地手动触发构建和提交的。现在都可以让 github action 帮我自动构建，定期提交到镜像仓库了

参考博客-使用 GitHub Actions 自动构建和推送 Docker 镜像到 Docker Hub

准备: dockerhub 开启二次登录 和 创建 token

首先为了账号尽量安全，不要在 Github 上直接配置账号密码（权限过大），我们需要在 Docker Hub 给自己的账号创建Token

参考-Create and manage access tokens

登录 Docker hub -> 右上角账号 -> Account Settings -> Security -> New Access Token

如上图，创建了一个 Github Action 专用 token ，因为需要提交/覆盖镜像 所以 Write 权限是需要的。当然这个权限还是比较大，我们还是需要注意保管好 不要泄露

然后将这个 token 在 github 中配置，登录 github -> 进入需要添加 action 任务的仓库 -> Settings -> Secrets and variables -> Actions -> New repository secret 。secret key 将作为任务的配置

准备: 项目中提供 Dockerfile

既然需要支持 通过 action 自动构建镜像，在项目中提供 Dockerifle 自然也是必须的

以 superset 为例，根路径下的 Dockerfile，action 文件中有发布镜像流程 docker-release.yml ，算是一个非常标准的参考项目了

如何给自己的服务编写 Dockerfile，也可以以不同语言的开源项目 Dockerfile 作为参考，对 Dockerfile 语法有一个大致了解就行。标准过程都是 定义编译镜像 -> 编译生成可执行文件 -> 定义服务运行镜像 -> 拷贝二进制文件 -> 定义服务启动指令

定义任务

以笔者项目 docker-centos 为例: 定期构建 python 开发环境镜像任务如下:

on:
  schedule:
  - cron: "0 3 * * 0" # 每周一3点（中时区）开始构建

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      - name: Login to DockerHub
        uses: docker/login-action@v1 
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }} # 对应前面配置的 docker hub 登录凭证
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: build_dev_python
        run: REPO=mzsmieli cmd=push platform=linux/amd64,linux/arm64 make build_dev_python # 该指令将触发 docker buildx build ... --push 进行镜像的构建和提交

效果

action 任务的执行记录

镜像仓库中，可以看到上次更新时间正好就是周一

单元测试覆盖率统计

一个完善的后台项目除了业务逻辑代码，还会包含大量的单元测试（即基本方法测试），用于正式上线前的自测。单元测试写得质量如何，其中一个重要评判标准就是单测覆盖率，即所有的单元测试所覆盖的业务代码行数 / 总业务代码行数 比例。覆盖率越高，说明单测越完整，实际上线时出现问题的概率也越低

而这个单测覆盖率的统计过程 如果能交给 Github Action 帮我们做，每天输出覆盖率报告，自然也能省不少心

项目准备

要统计单测覆盖率 当然我们要先给项目写好一部分单测。每种语言都会有自己的单测编写规范 和 单测框架库。框架库如何选择，可以在写单测之前了解一下 官方或者社区有没有比较流行好用的，选择一个自己用着更顺手的就行

规范这块则尽量参考官方文档，如一些后台语言的单测规范:

• go-testing
• python-unittest
• java-junit5

环境准备 - 创建 mysql service

参考-How to make MySQL work in your GitHub Actions

由于单测执行环境一般是在自己电脑 或者公司的测试环境，和线上环境是网络隔离的，我们需要给一些无法实际执行的函数写好mock 。所谓mock，就是让我们编写的函数 在特定输入下 返回特定输出，比如我们的服务对接 一个客户系统，在本地环境无法连上客户的环境，就需要 mock 用户服务的接口，自己写接口输出，来模拟真实环境的情况

对于业务层代码来说，写好 mock 取决于业务数据的分类规模。但对于更底层的数据接口层，如 gorm，需要 mock 的场景就更多了。比如业务层需要考虑 用户传入参数为 a、b、c 的输出，分别对应 d、e、f，那么数据接口层就要考虑 a、b、c 的首次存入、重复存入、事务存入等情况，除了 d、e、f 还需要返回各种错误提示。写好完整的 mock 比业务层要复杂多了

考虑到这点，数据库的交互部分我没有写 mock，而是直接通过 action 的 service 功能，启动一个 mysql 服务来完成项目中 需要依赖数据库的代码测试

定义任务

最终任务定义:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:5.7 # 通过官方的 5.7 版本镜像来启动 mysql
        env:
          MYSQL_ROOT_PASSWORD: root_password
        ports:
          - 3306:3306
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
          ref: master
      - name: setup goalng
        uses: actions/setup-go@v4
        with:
          go-version: '>=1.17.0'
      - name: init mysql
        run: |
          # 初始化单测需要用到的数据库表
          mysql -h127.0.0.1 -P3306 -uroot -proot_password -e "create database temp"
          mysql -h127.0.0.1 -P3306 -uroot -proot_password -Dtemp < db/mysql/mysql_test.sql
      - name: test
        run: |
          # 执行项目下的所有单测用例，并生成测试报告
          go test -covermode=count -coverprofile=coverprofile.cov -run="^Test" -coverpkg=$(go list ./... | grep -v "/test" | tr '\n' ',') ./...
      - name: Collect Test Coverage File
        uses: actions/upload-artifact@v3  # 上传测试覆盖率报告，即上个指令生成的 coverprofile.cov
        with:
          name: go_common_coverage
          path: coverprofile.cov

效果

执行记录和上传的文件:

github 首页构建

对个人开发者而言，github action 还可以用于 个人博客、应用app 的定期发布。github 首页就有点类似个人博客，可以按 markdown 语法编写内容，进行自我展示

我的 github 首页:

不过我还没有实现首页自动更新，这里以另一个github用户 E99p1ant 的 首页项目为例。他将首页的 markdown 文件内容写成了模板样式，通过 action 任务，定期读取模板 并生成最终展示的首页样式

如图 他的项目的 README_template.md 文件只是模板，实际内容来自同一个仓库的 profile.yml

任务定义

jobs:
  build:
    name: Update Profile
    runs-on: ubuntu-latest
    steps:
      - name: Set up Go 1.16
        uses: actions/setup-go@v1
        with:
          go-version: 1.16

      - name: Build & Run
        run: |
          # 执行主进程 将 模板文件 生成真正的首页效果
          # 过程: 读取 README_template.md 作为模板，profile.yml 作为内容，替换 template 中的 {{PROJECTS}} 和 {{CVE}}，生成最终的 README.md
          go build . && ./main && rm main

      - name: Git Commit
        run: |
          git add README.md
          git commit -S -m "Update README.md" || true # 内容没有变化时 commit 会报错，所以需要忽略报错，否则最后一步不会执行

      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: master

其他商用CI/CD工具

基本每个云厂商都会有 配套产品，如 Azure Pipeline, AWS CodePipeline 和 CircleCI 等

不过既然是商用 就代表具有一定的使用门槛，场景也受限，往往会和厂商的其他服务配套才能使用。如此一对比，就更凸显 Github Action 对我们个人开发者的易用性了

总结

从自己的实际体验来看，即使用上了 Github Action 也不会带来很明显的感知。但它带来的方便依然是存在的。就好像你在公司所用的所有基础设施（机器、数据库、sso服务等）一样。只有去刻意注意 才会发现它们的存在: 原来它们背后也凝聚了一群开发者的智慧，帮我们省去了非常多的工作

最后再分享前段时间看到的一段话:

但是像区块链这些东西，你就扪心自问一下，区块链是不是所有公司都在用？没有用就让那些猪在天上再飞一会，指不定哪天风停了呢。但是，今天那些很强劲的风已经刮了十多年、二十年了，你为啥不去呢？

不敢说 今年大火的 chatgpt 能有多少人真正用得上，因为刚刚以产品的形态进入公众视野，还没有沉淀下来。但是诸如 Github Action 这种 DevOps 工具，已经发展很多年，使用方式也在很多大厂得到了实践，那就没什么道理不去了解和学习