网站开发

5 GitHub Actions 手册

2019-08-24  本文已影响0人  水之心

学习资源：

学习 Actions

记录学习 Github Actions 的笔记。

学习资料：使用 GitHub 操作 自动化工作流程

1 GitHub 操作使用入门

GitHub 操作 可让您直接在 GitHub 仓库中创建自定义的软件开发生命周期工作流程。GitHub 操作的核心概念：

2 配置 worflow

如果您对某仓库具有写入或管理员权限，您可以创建、查看或编辑该仓库的工作流程。您可以根据工作流程中包含的操作类型自定义工作流程配置。

您可以在仓库中创建多个工作流程，但是必须将工作流程存储在仓库根目录的 .github/workflows 目录中。

工作流程必须至少有一项作业，并且作业包含一组用于执行个别任务的步骤。 步骤可以运行命令或使用操作。

您可以配置工作流程在 GitHub 事件发生时开始，按时间表开始，或者由外部事件触发。

您需要使用 YAML 语法配置工作流程，并将其在仓库中存储为工作流程文件。 在成功创建 YAML 工作流程文件并触发工作流程后，您会看到工作流程每个步骤的创建日志、测试结果、构件和状态。

2.1 创建工作流程文件

添加工作流程文件的步骤如下：

2.1.1 通过事件触发工作流程

事件：

要在 GitHub 上通过事件触发工作流程，请在工作流程名称后面添加 on:（指定触发 workflow 的条件，通常是某些事件）和事件值（如 push）。例如，工作流程在更改推送到仓库中的任何分支时触发：

name: descriptive-workflow-name
on: push

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

on: [push, pull_request]

要计划工作流程的运行，可以在工作流程文件中使用 POSIX cron 语法。 例如，工作流程每小时触发一次：

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
  - cron:  '0 * * * *'

下面的例子表示设定 workflow 运行的时间为周一至周五的 2:00 UTC 时间：

on:
  schedule:
  - cron: "0 2 * * 1-5"

要在外部事件发生后触发工作流程，您可以回调“创建仓库分发事件”REST API 端点来调用 repository_dispatch web 挂钩事件。 更多信息参阅 "Create a repository dispatch event" in GitHub 开发者文档。

更多信息和示例请参阅“触发工作流程的事件”。

2.1.2 过滤特定分支

您可以设置工作流程仅在特定分支上运行。

例如，工作流程限定在 master 分支上发生推送时运行：

on:
  push:
    branches:
    - master
    # file paths to consider in the event. Optional; defaults to all.
    paths:
      - test/*

有关在工作流程中引用分支的更多信息，请参阅“GitHub 操作 的工作流程语法”。

2.1.3 选择虚拟环境

您可以在 GitHub 托管的虚拟机上或者 Docker 容器中运行工作流程。可以为工作流程中的每项作业指定虚拟环境。

要指定想在其中运行工作流程的虚拟环境的操作系统、工具、软件包和设置，必须在工作流程文件中使用特殊语法。更多信息请参阅“GitHub 操作 的虚拟环境”。

您可以选择不同类型和版本的虚拟主机，包括 Ubuntu、Linux 和 macOS。 工作流程中的每项作业在同一虚拟环境中执行，让该作业中的操作使用文件系统共享信息。

要在全新的虚拟环境实例上运行作业，可以指定虚拟主机运行作业：

runs-on: ubuntu-18.04

有关详细信息，包括支持的版本，请参阅“GitHub 操作 的工作流程语法”。

2.1.4 配置构建矩阵

要同时在多个操作系统、平台和语言版本上测试，可以配置构建矩阵。构建矩阵提供不同的配置供虚拟环境测试。 例如，工作流程可为多个支持的语言、操作系统或工具版本运行作业。对于每项配置，将运行作业的副本并报告状态。您可以使用矩阵在 strategy: 下列出配置选项，在工作流程文件中指定构建矩阵。

例如，构建矩阵将通过不同版本的 Node.js、Ubuntu 和 Linux 操作系统运行作业：

strategy:
  matrix:
    node: [6, 8, 10]
    os: [ubuntu-14.04, ubuntu-18.04]

2.1.5 使用检出（checkout）操作

在工作流程中可以使用多个标准操作。检出操作是标准操作，在以下情况下，在工作流程中必须位于其他操作前面：

要使用标准检出操作而不做进一步的指定，请包含此步骤：

<br />- uses: actions/checkout@v1

此示例中使用 v1 确保您使用检出操作的稳定版本。

要浅层克隆仓库，或者只复制仓库的最新版本，请使用 with 语法设置 fetch-depth：

- uses: actions/checkout@v1
  with:
    fetch-depth: 1

更多信息请参阅检出操作。

2.1.6 选择用于工作流程的操作类型

您可以根据项目需求在工作流程中使用不同类型的操作：

更多信息请参阅“关于操作”。

选择要在工作流程中使用的操作类型时，建议探索公共仓库中或 Docker Hub 上的现有操作，并根据需要为项目自定义这些操作。

您可以在 github.com/actions 组织中找到并使用 GitHub 创建的操作。 要访问 Docker Hub，请参阅 Docker 网站上的“Docker Hub”。

2.1.7 在工作流程中引用操作

要在工作流程文件中使用正确的语法引用操作，必须考虑定义操作的位置。工作流程可以使用以下位置定义的操作：

要使用私人仓库中定义的操作，工作流程文件和操作必须在同一仓库中。您的工作流程不能使用在其他私人仓库中定义的操作，即使该仓库在同一组织中。为使工作流程在操作有更新时也保持稳定，您可以在工作流程文件中指定 Git 引用或 Docker 标记号以引用所用操作的版本。

从公共仓库引用操作：如果操作定义在公共仓库中，必须使用语法 {owner}/{repo}@{ref} 或 {owner}/{repo}/{path}@{ref} 引用操作。

jobs:
   my_first_job:
       name: My Job Name
       steps:
       - uses: actions/setup-node@v1
        with:
          node-version: 10.x

要查看完整的工作流程示例，请参阅设置节点模板仓库。下面简单列出一些说明：

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

再看一个完整的例子：

name: Greet Everyone
# This workflow is triggered on pushes to the repository.
on: [push]

jobs:
  build:
    # 作业名称为 Greeting
    name: Greeting
    # 此作业在 Linux 上运行
    runs-on: ubuntu-latest
    steps:
      # 此步骤使用 GitHub 的 hello-world-javascript-action：https://github.com/actions/hello-world-javascript-action
      - name: Hello world
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
        id: hello
      # 此步骤打印上一步操作的输出（时间）。
      - name: Echo the greeting's time
        run: echo 'The time was ${{ steps.hello.outputs.time }}.'

在工作流程文件使用操作的同一仓库中引用操作：如果操作在工作流程文件使用该操作的同一仓库中定义，您可以在工作流程文件中通过 ‌{owner}/{repo}@{ref} 或 ./path/to/dir 语法引用操作。

示例仓库文件结构：

.github
└── workflows
    └── my-first-workflow.yml
.
└── hello-world-action
    └── action.yml

示例工作流程文件：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    # This step checks out a copy of your repository.
    - uses: actions/checkout@v1
    # This step references the directory that contains the action.
    - uses: ./hello-world-action

引用 Docker Hub 上的容器：如果操作在 Docker Hub 上发布的 Docker 容器的镜像中定义，您必须在工作流程文件中通过 docker://{image}:{tag} 语法引用操作。为保护代码和数据，强烈建议先验证 Docker Hub 中 Docker 容器镜像的完整性后再将其用于工作流程。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

有关 Docker 操作的部分示例，请参阅 Docker-image.yml 工作流程或 Docker 操作仓库。

2.2 创建多个任务的 workflow

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

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

jobs:
  first_job:
    name: My first job
  second_job:
    name: My second job

上面代码的 jobs 字段包含两项任务，job_id 分别是 first_job 和 second_job。

有时，我们需要创建有依赖关系的任务，此时需要借助 needs 字段：

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

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

2.3 将工作流程状态徽章添加到您的仓库

状态徽章显示工作流程目前失败还是通过。 添加状态徽章的常见位置是仓库的 README.md 文件，但也可将其添加到您喜欢的任何网页。 徽章显示默认分支（通常是 master）的状态。 您也可以在 URL 中使用 branch 和 event 查询参数显示特定分支或事件运行的工作流程状态。具体的格式：

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

2.4 为操作创建自述文件

如果计划公开分享您的操作，建议创建自述文件以帮助人们了解如何使用您的操作。 您可以将此信息包含在 README.md 中：

配置工作流程：

构建操作

在 GitHub 上设置持续集成

上一篇下一篇

猜你喜欢

热点阅读