Github Actions使用教程
使用Github Actions实现全自动增量部署
Github Actions简介
[Github Actions\1(https://github.com/features/actions)是 GitHub于2018年10月推出的一个CI\CD服务。
CI/CD解释
CI\CD 其实说的是三件事情:「持续集成(Continuous Integration
)」、「持续交付(Continuous Delivery
)」、「持续部署(Continuous Deployment
)」。
因为「持续交付」和「持续部署」的英文缩写是一样的,所以这三件事情缩写成了 CI\CD
。
每次部署Hexo
都需要运行指令三件套,随着文章越来越多,编译的时间也随之越来越长,通过Github Actions
,我们只需要在每次完成博客的编写或修改以后,将改动直接push
到远程仓库,之后的编译部署的工作统统交给CI
来完成即可,如果是看过Coding部署教程的小伙伴,应该对这种持续部署的操作有所感触。
教程常量声明
感谢@YML的反馈。以下将使用特定的常量名来指代一些名词。此处建议读者直接使用教程内容的常量名。在最后再逐一搜索替换。这样可以避免对各种常量名的混淆。
常量名 | 常量释义 |
---|---|
[Blogroot] | 本地存放博客源码的文件夹路径 |
[SourceRepo] | 存放博客源码的私有仓库名 |
[SiteBlogRepo] | 存放编译好的博客页面的公有仓库名 Site指站点,教程中会替换成 Github、Gitee、Coding |
[SiteUsername] | 用户名 Site指站点,教程中会替换成 Github、Gitee、Coding |
[SiteToken] | 申请到的令牌码 Site指站点,教程中会替换成 Github、Gitee、Coding |
[GithubEmail] | 与github绑定的主邮箱,建议使用Gmail |
[TokenUser] | Coding配置特有的令牌用户名 |
1 | # 在记事本中逐个记录,方便替换,以下为我的示例。就是把这些资料都集中记录在一个记事本文件中。 |
Github Actions使用教程
获取Token
为了确保交由Github Actions
来持续部署时,Github Actions
具备足够的权限来进行hexo deploy
操作,需要先获取Token
,博主分别在Github
、Gitee
、Coding
处部署了静态页面,所以也就需要获取这三处的Token
。
访问Github->头像(右上角)->Settings->Developer Settings->Personal access tokens->generate new token,创建的Token
名称随意,但必须勾选repo项和workflows项。
token
只会显示这一次,之后将无法查看,所以务必保证你已经记录下了Token
。之后如果忘记了就只能重新生成重新配置了。
访问Gitee->头像(右上角)->设置->私人令牌->生成新令牌
Token
只会显示这一次,之后将无法查看,所以务必保证你已经记录下了Token
。之后如果忘记了就只能重新生成重新配置了。
创建存放源码的私有仓库
我们需要创建一个用来存放Hexo
博客源码的私有仓库[SourceRepo]
,这点在Win10的Hexo
博客搭建教程中有提到。为了保持教程的连贯,此处再写一遍。
创建完成后,需要把博客的源码push
到这里。首先获取远程仓库地址,此处虽然SSH
和HTTPS
均可。SSH
在绑定过ssh key
的设备上无需再输入密码,HTTPS
则需要输入密码,但是SSH
偶尔会遇到端口占用的情况。请自主选择。
SSH密钥与公钥的生成与使用
SSH密钥对包含两个部分,一个是公钥(public key),一个是私钥(private key)。私钥应始终保密,公钥则可以用于指定哪些使用配套私钥的用户可以访问你的服务。以下是在Linux、Mac OS或Windows的Git Bash终端中创建SSH密钥对的步骤:
- 打开你的命令行界面。
- 输入以下命令来创建一个新的SSH密钥对:
1 | ssh-keygen -t rsa -b 4096 -C "your_email@example.com" |
- ‘-t rsa’ 代表密钥类型(这里选择的是 RSA),‘-b 4096’ 表示密钥长度(4096位)
- ‘-C’ 是一个备注,通常填写你的邮箱,可以更容易地识别你的密钥。
- 当系统提示你 “Enter a file in which to save the key” (输入一个用于保存密钥的文件),你可以接受默认文件位置(一般都在C盘,注意观察一下),直接按 Enter。如果你想设置一个自定义的位置和名字,可以直接输入路径。
- 系统会提示你输入一个安全的密码(passphrase),这个密码将被用于保护你的私钥。你也可以选择不设置密码,直接按 Enter。
这个过程将会在 ~/.ssh 目录下(如果选择了默认设置)创建两个文件,id_rsa
和 id_rsa.pub
,分别是你的私钥和公钥。
下面是如何使用SSH公钥的一般步骤:
-
将你的公钥(
id_rsa.pub
文件中的内容)添加到远端服务器(如 Github)。为了将公钥添加到Github,你需要这样做:
在你的本地电脑打开 id_rsa.pub 文件,复制其中的全部内容。你可以使用很多方法打开这个文件,比如直接在文本编辑器中打开,或者在命令行中使用以下命令:
1
cat ~/.ssh/id_rsa.pub
该命令将输出你的公钥内容。
a. 登录你的GitHub账号,然后点击右上角的头像,选择"Settings"。
b. 在左侧的侧边栏,选择"SSH and GPG keys"。
c. 点击右上角的"New SSH key"按钮。
d. 在"Title"框中,输入这个SSH键的名称。你可以选择任何帮助你记忆这个键的名字。
e. 在"Key"框中,粘贴你刚才复制的公钥。
f. 点击"Add SSH key"按钮。
完成之后,你就可以使用你的私钥在你的电脑和GitHub之间建立安全的连接了。这意味着,当你进行Git操作的时候,无需再输入用户名和密码,系统将自动验证你的身份。
-
在使用SSH连接服务的时候,你只需要在你的本地机器上保存你的私钥,SSH客户端会自动使用你的私钥和远端服务器进行安全验证。
注意,不要泄漏你的私钥(id_rsa),这可能会导致你的服务被非法访问。如果你觉得你的私钥可能被泄漏,你需要立刻在所有服务上撤销这个公钥,然后生成一个新的密钥对。
配置Github Actions
- 在
[Blogroot]
新建.github
文件夹,注意开头是有个.
的。然后在.github
内新建workflows
文件夹,再在workflows
文件夹内新建autodeploy.yml
,在[Blogroot]/.github/workflows/autodeploy.yml
里面输入
1 | # 当有改动推送到master分支时,启动Actions |
注意最后一行的master:master
指从本地的master分支提交到远程仓库的master分支,需要根据你自己的实际情况进行调整(都改成main
即可)。本地分支可以在git bash中看到。线上分支可以在提交仓库中查看。因为“政治正确”的原因,github在2020年10月将默认分支改为main。而git软件在本地默认创建的分支依然是master,所以若你线上仓库默认分支是main,这里应该写成master:main,表示从本地的master推送到远程的main。
这里主要在于配置上文的安装依赖和生成静态文件,如果还安装了其他的需要在部署前输入相应指令的也可以按照这个思路来修改。
同时,此处还涉及到Gitee的自动部署
,即使不开通Gitee pages pro,也可以完成自动更新。
详情可以访问卓越科技-使用Github Actions 自动部署博客
插件配置教程则是参考以下文档
- hexo-bilibili-bangumi,使用该插件若是无效,请检查你的B站追番信息是否是公开的,在个人空间处设置。
- Butterfly文档-gulp压缩
- Gitee Pages Actions
1 | name: 自动部署 |
注意最后一行的master:master
指从本地的master分支提交到远程仓库的master分支,需要根据你自己的实际情况进行调整。本地分支可以在git bash中看到。线上分支可以在提交仓库中查看。因为“政治正确”的原因,github在2020年10月将默认分支改为main。而git软件在本地默认创建的分支依然是master,所以若你线上仓库默认分支是main,这里应该写成master:main,表示从本地的master推送到远程的main。
这里的GITEE_RSA_PRIVATE_KEY指你的个人密钥,在配置SSH-KEY时,我们用来与Github绑定的是公钥,而私钥存放在(以win10为例)C:\Users\userneme\.ssh\id_rsa
文件内,内容格式类似于下方代码,使用时将包括-----BEGIN RSA PRIVATE KEY-----
和-----END RSA PRIVATE KEY-----
在内的全部内容都存放到变量值里。
1 | -----BEGIN RSA PRIVATE KEY----- |
可能遇到的bug:
- Gitee用github actions自动部署更新收到短信,提示异地登录需要验证码。
因为github actions使用的是美国的服务器,所以,使用github Actions来远程更新gitee的站点部署时,会收到异地登陆的短信,提示需要验证码。这个在脚本作者的issues里有相应的解决方案:登陆失败 #6- 在微信上搜索Gitee微信公众号,在微信公众号内绑定自己的Gitee账号,这样虽然还是会有异地登录提示,但是发过来的消息不再需要填写验证码,而且提醒若不是你在操作,请及时修改密码。(某种意义上就是我在操作,所以我选择不改密码2333)
- 使用VPN,通过美国IP登录一次Gitee。(一般第一步就能把问题解决了,用不到第二步。)
- Gitee部署失败
脚本的原理是用程序代替人工去点击Gitee Pages的更新按钮。所以需要你先手动做一次页面部署,确保有那个更新按钮在,脚本才有生效的前提。
- 之后需要自己到仓库的Settings->Secrets and variables->actions 下添加环境变量,变量名参考脚本中出现的,依次添加(有改动,请注意上方代码注释)
例如,脚本中必要的变量为
GITHUBUSERNAME
、GITHUBEMAIL
、GITHUBTOKEN
、GITHUBPNAME
,因此添加这4条变量。变量具体内容释义可以查看本文开头。
重新设置远程仓库和分支
- 添加屏蔽项
因为能够使用指令进行安装的内容不包括在需要提交的源码内,所有我们需要将这些内容添加到屏蔽项,表示不上传到github上。这样可以显著减少需要提交的文件量和加快提交速度。
打开[Blogroot]/.gitignore
,输入以下内容:
1 | .DS_Store |
如果不是butterfly
主题,记得替换最后一行内容为你自己当前使用的主题。
- 提交源码到私有仓库
[SourceRepo]
在博客根目录[Blogroot]下启动终端,使用git指令重设仓库地址。这样在新建仓库,我们仍旧可以保留珍贵的commit history,便于版本回滚。
1 | git remote rm origin # 删除原有仓库链接 |
- 可能遇到的bug
因为butterfly
主题文件夹下的.git
文件夹的存在,那么主题文件夹会被识别子项目。从而无法被上传到源码仓库。若是遇到添加屏蔽项,但是还是无法正常上传主题文件夹的情况。请先将本地源码中的themes
文件夹移动到别的目录下。然后commit
一次。接着将themes
文件夹移动回来,再commit
一次。
要是还不行,那就删了butterfly
主题文件夹下的.git
文件夹,然后再重复上述的commit
操作
- 删除或者先把
[Blogroot]/themes/butterfly/.git
移动到非博客文件夹目录下,原因是主题文件夹下的.git
文件夹的存在会导致其被识别成子项目,从而无法被上传到源码仓库。 - 在博客根目录
[Blogroot]
路径下运行指令
1 | git init #初始化 |
- 添加屏蔽项
因为能够使用指令进行安装的内容不包括在需要提交的源码内,所有我们需要将这些内容添加到屏蔽项,表示不上传到github上。这样可以显著减少需要提交的文件量和加快提交速度。
打开[Blogroot]/.gitignore
,输入以下内容:
1 | .DS_Store |
- 如果不是
butterfly
主题,记得替换最后一行内容为你自己当前使用的主题。
之后再运行git提交指令,将博客源码提交到github上。牢记下方的三行指令,以后都是通过这个指令进行提交。
1 | git add . |
- 此时你的主题文件夹若已经被正常上传,并且你也添加了主题文件夹下的.git文件夹的屏蔽项。那你可以考虑把第二步移走或删除的
.git
放回来,用作以后升级。(不禁怀疑真的有人会去用这个方式来升级吗)
查看部署情况
此时,打开GIthub存放源码的私有仓库,找到Actions。
根据刚刚的Commit记录(messages
信息)找到相应的任务
点击Deploy查看部署情况
若全部打钩,恭喜你,你现在可以享受自动部署的快感了。
可能遇到的bug
要是在github action部署时遇到unknown block tag: "tagname"
这样的报错,说明你可能没有正确上传主题文件夹,也可能遇到安装依赖或生成页面失败的情况。
- 是否将
node_modules
也上传到源码仓库[SourceRepo]
了。源码仓库不需要有node_modules
文件夹。 - 是否有将
[Blogroot]/themes/
下的主题文件夹上传,例如检查[SourceRepo]内的[Blogroot]/themes/Butterfly
是否为空文件夹。为了能够正常编译页面,源码仓库需要有[Blogroot]/themes/Butterfly
文件夹及它所包含的主题文件内容。
为了避免这两点,需要添加git屏蔽项。通过给.gitignore
添加屏蔽项解决。
打开[Blogroot]/.gitignore
,输入以下内容:
1 |
|
- 若是遇到添加屏蔽项,但是还是无法正常上传主题文件夹的情况。
- 请先将本地源码中的
themes/butterfly
文件夹下的.git
文件夹删除。 - 然后将
butterfly
文件夹移动到别的目录下。然后commit
一次。 - 接着将
butterfly
文件夹移动回来,再commit
一次。
若是遇到spawn failed
报错。在github actions
的配置中出现这一报错。一般是因为涉及到部署地址的配置项有误。
- 首先排查你在
[Blogroot]\_config.yml
的deploy
配置项是否按照上文配置deploy项中的步骤正确组装配置链接。 - 其次排查
[Blogroot]\.github\workflows\autodeploy.yml
中各个关于仓库链接的配置内容,注意按照注释指引检查空格、分支等。 - 更多可能的因素和解决方案可以参考@洪哥HEO写的方案:Hexo错误:spawn failed的解决方法。
部分不愿意用教程给出的变量名的可能遇到未知bug,此处给出官方的命名规则:
以下规则适用于密码名称:
密钥名称只能包含字母数字字符([a-z]、[A-Z]、[0-9])或下划线 (_)。 不允许空格。
密钥名称不得以 GITHUB_
前缀开头。
密钥名称不能以数字开头。
密钥名称不区分大小写。
密钥名称在所创建的级别上必须是唯一的。
本地分支和线上分支不一致导致总是提交不上。
注意观察autodeploy.yml文件中
末尾的master:master指从本地的master分支提交到远程仓库的master分支。需要根据实际情况进行调整。本地的分支可在git bash中查看。线上的分支可在仓库查看。比如本地默认分支是master,线上默认分支是main,应该改成master:main。
会遇到这类问题,一般是有同学直接全局替换master为main导致。
错误信息 fatal: repository 'https://github.com/***/***.github.io.git/' not found
表示 git
无法找到你想要推送的 GitHub 仓库。
可能的原因有以下几个:
- 仓库不存在: 检查你的 GitHub 仓库是否确实存在,仓库名是否输入正确(大小写、拼写等)。
- Secrets 变量错误:确认 GitHub Actions 的 secrets 有正确地设置,所有变量名及其值都是正确的,并且确实存在。尝试在 GitHub 仓库的 “Settings” 菜单下的 “Secrets” 选项中查看和确认这些值。
- 权限问题:检查你的
GITHUBTOKEN
是否有合适的权限,至少要有对应仓库的写权限。 - 仓库名问题:仓库名
$.github.io.git
中包含.github.io
,这通常用于 GitHub Pages服务,如果你的仓库并非用于此,那可能不需要这部分。
快速检查是否是仓库名问题的一种方式就是,尝试将命令中的
$.github.io.git
改为$.git
,然后再进行尝试。
在git commit
下方加入git checkout -b main
,检出(切换到)main
分支,如果没有,则创建一个新的名为main
的branch
。
如果你想改变你的项目关联的远程仓库地址,你可以使用 git remote set-url origin your-new-git-url.git
来更改。这里的 “your-new-git-url.git” 就需要替换为你新的GitHub仓库的 URL地址。
后记
这里可能有同学要问,github actions有啥用?这不就是从hexo cl && hexo g && hexo s
的三件套变成了git add .
,git commit -m "commit content"
,git push
三件套吗?
其实github action的最大作用就是进一步提高速度和便携性,首先,配置要求提交源码这点,萌新小白就没必要再靠本地不断新建压缩包来备份源码了,借助git的版本管理,不管怎么改都可以快速回滚。
然后,git提交是增量更新,每次只提交新增或者删改的内容,而hexo deploy是在本地每次重新生成所有静态文件以后再整个提交。github action能帮我们节省大把时间,把最耗时的hexo generate和hexo deploy的工作丢给CI处理。让我们能够专心与编写博客内容,而不是水文3分钟,提交半小时。
发散思维
Github actions
只要监测到master
分支有所变动就会启动部署,那么顺着这个思路,手机用户可以在网页Github进行小幅修改,例如修改错别字,调整布局之类的。保存后也会启动Github actions
,从而将内容部署到网页上去。
PS:
本博文原地址为:https://akilar.top/posts/f752c86d/,
Ai-China结合自己的路程进行了些微修改和备注,希望于人有益。
感谢原作者的艰辛创作!