GitHub Actions 入门教程

作者: 阮一峰

日期: 2019年9月12日

腾讯课堂 NEXT 学院

GitHub Actions 是 GitHub 的持续集成服务,于2018年10月推出

这些天,我一直在试用,觉得它非常强大,有创意,比 Travis CI 玩法更多。

本文是一个简单教程,演示如何使用 GitHub Actions 自动发布一个 React 应用到 GitHub Pages

一、GitHub Actions 是什么?

大家知道,持续集成由很多操作组成,比如抓取代码、运行测试、登录远程服务器,发布到第三方服务等等。GitHub 把这些操作就称为 actions。

很多操作在不同项目里面是类似的,完全可以共享。GitHub 注意到了这一点,想出了一个很妙的点子,允许开发者把每个操作写成独立的脚本文件,存放到代码仓库,使得其他开发者可以引用。

如果你需要某个 action,不必自己写复杂的脚本,直接引用他人写好的 action 即可,整个持续集成过程,就变成了一个 actions 的组合。这就是 GitHub Actions 最特别的地方。

GitHub 做了一个官方市场,可以搜索到他人提交的 actions。另外,还有一个 awesome actions 的仓库,也可以找到不少 action。

上面说了,每个 action 就是一个独立脚本,因此可以做成代码仓库,使用userName/repoName的语法引用 action。比如,actions/setup-node就表示github.com/actions/setup-node这个仓库,它代表一个 action,作用是安装 Node.js。事实上,GitHub 官方的 actions 都放在 github.com/actions 里面。

既然 actions 是代码仓库,当然就有版本的概念,用户可以引用某个具体版本的 action。下面都是合法的 action 引用,用的就是 Git 的指针概念,详见官方文档


actions/setup-node@74bc508 # 指向一个 commit
actions/setup-node@v1.0    # 指向一个标签
actions/setup-node@master  # 指向一个分支

二、基本概念

GitHub Actions 有一些自己的术语。

(1)workflow (工作流程):持续集成一次运行的过程,就是一个 workflow。

(2)job (任务):一个 workflow 由一个或多个 jobs 构成,含义是一次持续集成的运行,可以完成多个任务。

(3)step(步骤):每个 job 由多个 step 构成,一步步完成。

(4)action (动作):每个 step 可以依次执行一个或多个命令(action)。

三、workflow 文件

GitHub Actions 的配置文件叫做 workflow 文件,存放在代码仓库的.github/workflows目录。

workflow 文件采用 YAML 格式,文件名可以任意取,但是后缀名统一为.yml,比如foo.yml。一个库可以有多个 workflow 文件。GitHub 只要发现.github/workflows目录里面有.yml文件,就会自动运行该文件。

workflow 文件的配置字段非常多,详见官方文档。下面是一些基本字段。

(1)name

name字段是 workflow 的名称。如果省略该字段,默认为当前 workflow 的文件名。


name: GitHub Actions Demo

(2)on

on字段指定触发 workflow 的条件,通常是某些事件。


on: push

上面代码指定,push事件触发 workflow。

on字段也可以是事件的数组。


on: [push, pull_request]

上面代码指定,push事件或pull_request事件都可以触发 workflow。

完整的事件列表,请查看官方文档。除了代码库事件,GitHub Actions 也支持外部事件触发,或者定时运行。

(3)on.<push|pull_request>.<tags|branches>

指定触发事件时,可以限定分支或标签。


on:
  push:
    branches:    
      - master

上面代码指定,只有master分支发生push事件时,才会触发 workflow。

(4)jobs.<job_id>.name

workflow 文件的主体是jobs字段,表示要执行的一项或多项任务。

jobs字段里面,需要写出每一项任务的job_id,具体名称自定义。job_id里面的name字段是任务的说明。


jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

上面代码的jobs字段包含两项任务,job_id分别是my_first_jobmy_second_job

(5)jobs.<job_id>.needs

needs字段指定当前任务的依赖关系,即运行顺序。


jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

上面代码中,job1必须先于job2完成,而job3等待job1job2的完成才能运行。因此,这个 workflow 的运行顺序依次为:job1job2job3

(6)jobs.<job_id>.runs-on

runs-on字段指定运行所需要的虚拟机环境。它是必填字段。目前可用的虚拟机如下。

  • ubuntu-latestubuntu-18.04ubuntu-16.04
  • windows-latestwindows-2019windows-2016
  • macOS-latestmacOS-10.14

下面代码指定虚拟机环境为ubuntu-18.04


runs-on: ubuntu-18.04

(7)jobs.<job_id>.steps

steps字段指定每个 Job 的运行步骤,可以包含一个或多个步骤。每个步骤都可以指定以下三个字段。

  • jobs.<job_id>.steps.name:步骤名称。
  • jobs.<job_id>.steps.run:该步骤运行的命令或者 action。
  • jobs.<job_id>.steps.env:该步骤所需的环境变量。

下面是一个完整的 workflow 文件的范例。


name: Greeting from Mona
on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

上面代码中,steps字段只包括一个步骤。该步骤先注入四个环境变量,然后执行一条 Bash 命令。

四、实例:React 项目发布到 GitHub Pages

下面是一个实例,通过 GitHub Actions 构建一个 React 项目,并发布到 GitHub Pages。最终代码都在这个仓库里面,发布后的参考网址为ruanyf.github.io/github-actions-demo

第一步,GitHub Actions 目前还处在测试阶段,需要到这个网址申请测试资格。申请以后,可能需要几天才能通过。据说,2019年11月就会放开。

获得资格后,仓库顶部的菜单会出现Actions一项。

第二步,这个示例需要将构建成果发到 GitHub 仓库,因此需要 GitHub 密钥。按照官方文档,生成一个密钥。然后,将这个密钥储存到当前仓库的Settings/Secrets里面。

上图是储存秘密的环境变量的地方。环境变量的名字可以随便起,这里用的是ACCESS_TOKEN。如果你不用这个名字,后面脚本里的变量名也要跟着改。

第三步,本地计算机使用create-react-app,生成一个标准的 React 应用。


$ npx create-react-app github-actions-demo
$ cd github-actions-demo

然后,打开package.json文件,加一个homepage字段,表示该应用发布后的根目录(参见官方文档)。


"homepage": "https://[username].github.io/github-actions-demo",

上面代码中,将[username]替换成你的 GitHub 用户名,参见范例

第四步,在这个仓库的.github/workflows目录,生成一个 workflow 文件,名字可以随便取,这个示例是ci.yml

我们选用一个别人已经写好的 action:JamesIves/github-pages-deploy-action,它提供了 workflow 的范例文件,直接拷贝过来就行了(查看源码)。


name: GitHub Actions Build and Deploy Demo
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@master

    - name: Build and Deploy
      uses: JamesIves/github-pages-deploy-action@master
      env:
        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        BRANCH: gh-pages
        FOLDER: build
        BUILD_SCRIPT: npm install && npm run build

上面这个 workflow 文件的要点如下。

  1. 整个流程在master分支发生push事件时触发。
  2. 只有一个job,运行在虚拟机环境ubuntu-latest
  3. 第一步是获取源码,使用的 action 是actions/checkout
  4. 第二步是构建和部署,使用的 action 是JamesIves/github-pages-deploy-action
  5. 第二步需要四个环境变量,分别为 GitHub 密钥、发布分支、构建成果所在目录、构建脚本。其中,只有 GitHub 密钥是秘密变量,需要写在双括号里面,其他三个都可以直接写在文件里。

第五步,保存上面的文件后,将整个仓库推送到 GitHub。

GitHub 发现了 workflow 文件以后,就会自动运行。你可以在网站上实时查看运行日志,日志默认保存30天。

等到 workflow 运行结束,访问 GitHub Page,会看到构建成果已经发上网了。

以后,每次修改后推送源码,GitHub Actions 都会自动运行,将构建产物发布到网页。

五、参考链接

(完)

留言(34条)

这样貌似可以制作静态博客网站

现在使用 netlify 和 GitHub Pages 配合 actions 搭建个人站点,再加上公共 CDN,体验很好了。

引用Rw的发言:

这样貌似可以制作静态博客网站

甚至可以动态吧

为啥我在github上还看不到action

我的Hexo博客 终于可以不用自己那一套Hook了.... 这个方法感觉优雅多了。

引用小兵的发言:

为啥我在github上还看不到action

要github审核通过才有

我之前用的hook 加jenkins.这个action 看起来能替代我之前的流程

正惊讶今天怎么没等到科技爱好者周刊,才想起来还没到周五呢

阮老师中秋快乐!

runs-on 可以使用自定义的image吗?如果test任务依赖mysql,如何解决呢?

要是介绍一波自己写的 action 就好了, 我现在一直卡死在 push 处, 上不去.

感觉和Travis CI区别不大

自定义的trigger? Server less?

阮大神可以讲讲react+dva-cli吗,我最近在写但是,看了官方文档还是,不太懂

刚刚试了,action权限秒开....突然萌生出一个想法,舍弃hexo,用react自己写个。这样我的博客主题我做主。哈哈哈哈哈哈哈。

阮一峰老师,您有一个地方没写,就是要在 package.json 中加入 homepage 字段,否则github pages会找不到 js 和 css 文件。

发现Fork之后不会运行,可以自己建个仓库再把阮老师的代码push上去,我运行的效果https://github.com/gaohanghang/github-actions-demo/actions

@郑明远:

谢谢指出,我确实忘了,已经补上。

请问这个怎么配置到github pages上呢?

申请就通过

感谢阮大大分享。说的很详细很清晰,立马申请个action试试!

另外,提一点个人浅见。 文中提到的“秘密变量”,如果改成叫“私密变量” 会不会好理解一些? 出现地方有:

1:

```
上图是储存[秘密]的环境变量的地方。环境变量的名字可以随便起,这里用的是ACCESS_TOKEN。
```

改成=》

```
上图是存储私密的环境变量的地方。…………
```

2:

```
第二步需要四个环境变量,分别为 GitHub 密钥、发布分支、构建成果所在目录、构建脚本。其中,只有 GitHub 密钥是[秘密变量],需要写在双括号里面,其他三个都可以直接写在文件里。
```

改成=>

```
…………其中,只有 GitHub 密钥是私密变量,…………
```

个人浅见,说的不对的地方还请见谅。

有个问题:仅执行 npm install && npm run build 没有运行 gh-pages -d build 为什么会自动生成 gh-pages 分支呢?(我的 https://[user.name].github.io 是新建的一个项目名字叫做 [user.name].github.io )

感谢大佬。尝试做一个基于vuepress的静态博客,自己写的action脚本老出问题,参考这个一次成功。

引用simon-woo的发言:

有个问题:仅执行 npm install && npm run build 没有运行 gh-pages -d build 为什么会自动生成 gh-pages 分支呢?(我的 https://[user.name].github.io 是新建的一个项目名字叫做 [user.name].github.io )

分支和推送分支包括一些目录对应之类的处理都在引用的那个action脚本里JamesIves/github-pages-deploy-action@master

如果是常规的开发流程,打包好Push到Github,自动发布到公司服务器,怎么建立Github与公司服务器的联系?

可以执行CI,但是怎么在gitpage查看到效果呢

为什么CI执行action完成之后,gitpage要刷新好久才能出来

引用simon-woo的发言:

如果是常规的开发流程,打包好Push到Github,自动发布到公司服务器,怎么建立Github与公司服务器的联系?

我用这个插件 easingthemes/ssh-deploy@v2.0.7 可以打包发到服务器

老师您好,我想请问一下如果我之前使用hexo部署了我的博客,地址是我的[username].github.io,现在再使用action部署上去访问就会404,我是应该把原先的博客也使用action的方式部署么?谢谢老师解惑

我的情况看来和@Echo一样,部署完也是404

我用github action 搭建了自己的hexo blog https://dev4mobiles.com,
源码在develop 分支上: https://github.com/dev4mobile/dev4mobile.github.io

引用Echo的发言:

老师您好,我想请问一下如果我之前使用hexo部署了我的博客,地址是我的[username].github.io,现在再使用action部署上去访问就会404,我是应该把原先的博客也使用action的方式部署么?谢谢老师解惑

同样的问题...

测试了一下。CI 成功,Git pages 失败

查看了 github action 的构建构成发现 阮老师和我的构建和步骤细节不太一样了呢。所以案例可能失效了吧。

我要发表看法

«-必填

«-必填,不公开

«-我信任你,不会填写广告链接