1、前提条件
- git仓库commit提交记录不为空，能提取有价值信息。
- commit记录有统一的格式，如Angular 规范。
2、生成时机
Changelog 生成最合适的时机，是在完成代码提交创建新 Tag 时。代码仓得到一个 Tag，将其推送到远端，同时生成该tag对应的版本更新记录。
3、方案选择
驱使gitlab自动生成changelog，大致有三种方案：
- 1.通过runner操作release-cli镜像实现，要求gitlab 13.2以上版本;
release_job:
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
rules:
# 只有当 Tag 被创建的时候才执行该任务
- if: $CI_COMMIT_TAG
script:
- echo 'running release_job'
# 使用命令行生成 Changelog
# 该命令行可以根据需求自定义
- export EXTRA_DESCRIPTION=$(changelog)
release:
name: 'Release $CI_COMMIT_TAG'
# 将得到的 Changelog 填入 description 字段
description: '$EXTRA_DESCRIPTION'
tag_name: '$CI_COMMIT_TAG'
ref: '$CI_COMMIT_TAG'
- 2.通过gitlab-ci执行shell脚本实现，需要修改每个项目.gitlab-ci.yml脚本；
- 3.通过gitlab webhook通知三方系统，执行changelog生成任务。
本文采用的第3个方案，优点是changelog生成任务独立，不用改变原有项目构建任务，可复用devops工具Jenkins，启用只需要勾选Tag push Event 即可。
4、实现过程
利用webhook钩子，生成changelog记录分为三步：Tag事件触发webhook消息、拉取代码整理commit记录、写commit记录到changelog文档。
4.1启用gitlab的webhook消息
gitlab webhook触发Jenkins任务最便捷的方式，是通过Generic Webhook Trigger插件，可通过Jenkins的插件管理功能安装，此处主要讲配置过程。
1、新建Jenkins任务，Build Triggers勾选Generic Webhook Trigger复选框，HTTP requests链接地址，为gitlab webhook要配置的通知地址。
2、新增Post content parameters，配置从webhook消息中提取的变量，变量名Variable 随便定义，Expression 中都是请求头里面存在的json格式的key。勾选Print post content选项，可以在Jenkins任务执行日志中，打印请求的请求体内容。请求体json示例如下：
{"object_kind":"tag_push", #触发类型，有tag推送或者分支推送等
"before":"0000000000000000000000000000000000000000", #推送前的id ，如果为00..表示新建
"after":"c4365c6029f00aeddf33dab026c2590312ed6743", #新建tag 后的id
"ref":"refs/tags/v0.7dev", #推送的tag。通过$.ref 来提取
"checkout_sha":"c4365c6029f00aeddf33dab026c2590312ed6743",
"message":null, #message表示打tag 的时候标注的备注信息，例如git tag v1.1 -m "备注信息"
"user_id":435,
"user_name":"kzf",
"user_email":"kzf-pbj@asdf.com","project_id":796,
"repository":{"name":"practice", #仓库信息如下
"url":"git@x.x.x.x:kzf/practice.git",
"description":"个人练习使用",
"homepage":"http://git@x.x.x.x:kzf/practice",
"git_http_url":"http://x.x.x.x/kzf/practice.git",
"git_ssh_url":"git@x.x.x.x:kzf/practice.git",
"visibility_level":10},
"commits":[{"id":"c4365c6029f00aeddf33dab026c2590312ed6743", #commits里面是列表，通过$..commits[0]表示提取它的第一个列表所有内容
"message":"del dev1\n", #提交的时候的commit 信息，例如git commit -m "提交信息"，
"timestamp":"2020-04-12T18:17:16+08:00", #$..commit[0].timestamp 表示提取此字段
"url":"http://x.x.x.x/kzf/practice/commit/c4365c6029f00aeddf33dab026c2590312ed6743",
"author":{"name":"feefsdf","email":"feefsdf@asdf.com"}}],
"total_commits_count":1}
参照json消息，配置Post content parameters示例如下：
3、请求验证token，用于Jenkins收到webhook消息后，判断具体触发哪个任务，用于每个项目单独创建Jenkins job场景。token放在URL中，例如：http://JENKINS_URL/generic-webhook-trigger/invoke？token=test1
4、Optional filter过滤项用于条件判断，Text中的变量只有符合Expression项设置的条件 ，才会触发Jenkins任务。Text处的变量名，必须是Post content parameters 区域提取过的。
5、gitlab上webhook配置，找到启用webhook的gitlab项目，编辑>webhooks，添加触发Jenkins任务的HTTP requests链接，勾选触发事件即可。
4.2制定Jenkins执行任务
在4.1的配置中，完成了webhook发送和接收的配置，只是触发了Jenkins任务，具体的changelog生成逻辑需要在具体shell脚本中完成，可以在gitlab中新增git仓用于存放，如changelog-create项目。
修改4.1中创建的Jenkins任务，编辑Source Code Management项，配置changelog-create项目的信息，用于每次任务启动拉取changelog生成脚本。
配置Jenkins任务，执行changelog生成的shell脚本，传入Generic Webhook Trigger中提取的变量。
4.3写changelog入文档库
经过以上步骤，webhook钩子触发Jenkins配置工作完成，接下来进行具体脚本编写。changelog.sh示例如下：
#!/bin/bash
## Author cuiSW
##1.根据传入变量拉取项目代码
#$1 项目库git地址
#$2 项目名称
set -e
git_url=${1:-'no_run'}
docs_name=${2:-'no_run'}
if [[ $git_url = 'no_run' ]] || [[ $docs_name = 'no_run' ]]; then
echo "no run"
exit 1
fi
#克隆项目代码，账号/密码为gitlab登录信息
git clone `${git_url:0:8}账号:密码${git_url:8}`
echo "git clone success"
#代码项目名称
temp_name=${docs_name##*/}
if [ -d $temp_name ]; then
cd $temp_name
#切换至master，默认就在master分支
git checkout master
#拉取代码
git pull
else
echo "clone fail"
exit 1
fi
##2.调用自定义脚本生成changelog
# solve the space by IFS
IFS=`echo -en "\n\b"`
echo -en $IFS
if [ -f "CHANGELOG.md" ];then
rm -f CHANGELOG.md
touch CHANGELOG.md
else
touch CHANGELOG.md
fi
function printFeat(){
for i in ${feat[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printFix(){
for i in ${fix[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printPerf(){
for i in ${perf[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printStyle(){
for i in ${style[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printRefactor(){
for i in ${refactor[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printCI(){
for i in ${ci[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printTest(){
for i in ${test[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printDocs(){
for i in ${docs[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function printChore(){
for i in ${chore[@]}
do
echo "- "$i >> CHANGELOG.md
done
}
function checkLog(){
if [[ $1 == "feat"* ]]
then
feat[featIndex]=$1
let featIndex++
elif [[ $1 == "fix"* ]]
then
fix[fixIndex]=$1
let fixIndex++
elif [[ $1 == "perf"* ]]
then
perf[perfIndex]=$1
let perfIndex++
elif [[ $1 == "style"* ]]
then
style[styleIndex]=$1
let styleIndex++
elif [[ $1 == "refactor"* ]]
then
refactor[refactorIndex]=$1
let refactorIndex++
elif [[ $1 == "test"* ]]
then
test[testIndex]=$1
let testIndex++
elif [[ $1 == "ci"* ]]
then
ci[ciIndex]=$1
let ciIndex++
elif [[ $1 == "docs"* ]]
then
docs[docsIndex]=$1
let docsIndex++
elif [[ $1 == "chore"* ]]
then
chore[choreIndex]=$1
let choreIndex++
fi
}
function printLog(){
if [[ $featIndex -ne 0 ]]; then
echo "### Features" >> CHANGELOG.md
printFeat
fi
if [[ $fixIndex -ne 0 ]]; then
echo "### Bug Fixes" >> CHANGELOG.md
printFix
fi
if [[ $perfIndex -ne 0 ]]; then
echo "### Performance" >> CHANGELOG.md
printPerf
fi
if [[ $styleIndex -ne 0 ]]; then
echo "### Format Styles" >> CHANGELOG.md
printStyle
fi
if [[ $refactorIndex -ne 0 ]]; then
echo "### Improve Codes" >> CHANGELOG.md
printRefactor
fi
if [[ $testIndex -ne 0 ]]; then
echo "### Test Cases" >> CHANGELOG.md
printTest
fi
if [[ $ciIndex -ne 0 ]]; then
echo "### CI Scripts" >> CHANGELOG.md
printCI
fi
if [[ $docsIndex -ne 0 ]]; then
echo "### DOC Changes" >> CHANGELOG.md
printDocs
fi
if [[ $choreIndex -ne 0 ]]; then
echo "### Dependencies" >> CHANGELOG.md
printChore
fi
feat=()
featIndex=0
fix=()
fixIndex=0
perf=()
perfIndex=0
style=()
styleIndex=0
refactor=()
refactorIndex=0
test=()
testIndex=0
ci=()
ciIndex=0
docs=()
docsIndex=0
chore=()
choreIndex=0
}
curTag=""
function checkTag()
{
if [[ $curTag = $1 ]]; then
return
fi
curTag=$1
printLog
echo "----------------------------------">> CHANGELOG.md
echo "## "$curTag >> CHANGELOG.md
}
commitMessageList=`git log --oneline --date=format:'%Y-%m-%d' --format='%d%cd%n%s'`
#commitMessageList=`git log --oneline --format='%d%cs%n%s'`
for i in ${commitMessageList[@]}
do
if [[ $i == *'tag'* ]]
then
i=$(echo ${i//", origin/master, origin/HEAD"/}|sed s/"HEAD -> master, "//g)
checkTag $i
else
checkLog $i
fi
done
printLog
##3、写入文档库
#读取changelog 文件内容
text=$(cat ./CHANGELOG.md)
#进行urlencode编码
urlEncodetext=`echo -n "$text" | xxd -ps | tr -d '\n' | sed -r 's/(..)/%\1/g'`;
#访问具体文档库，可以是wiki、gitlab、zentao，调用接口将生成的changelog写入，代码略
以上代码完成了gitlab具体项目代码拉取，commit信息整理，以及changelog.md文件的生成工作。可在Jenkins构建目录下，查看changelog.md文件，具体写入的归档位置可根据实际补充。
