GitHub Actions 发布至 GitHub Marketplace_综合

文章目录

- 编写 metadata file
- - 定义输入参数
  - 定义运行步骤
  - - JavaScript 运行方式
    - Docker 运行方式
    - 组合运行方式
  - 示例
- 发布至 GitHub Marketplace
- 参考

GitHub Actions 是 GitHub 提供的一款 CI/CD（持续集成/持续部署）工具，可以帮助我们自动构建、测试、编译、打包、部署项目，功能十分强大

GitHub Marketplace 中收录了许多官方和第三方开发者所发布的一系列 actions

下面以本人所发布的 Bark Notify 为例，讲述将自己开发的 action 发布到 GitHub Marketplace 的详细过程以及在开发过程中遇到的坑

编写 metadata file

action 由一个 YAML 语法的元数据文件所定义，因此须在仓库中新建一个 action.yml 或 action.yaml 文件作为 action 的入口

You can create actions to perform tasks in your repository. Actions require a metadata file that uses YAML syntax.

——Metadata syntax for GitHub Actions

以下是元数据文件中的几个关键字段

name: action 的名称，也是在 GitHub Marketplace 中所展示的名称
author: 作者信息
description: aciton 的简短描述
inputs: 定义输入参数集合，可以包含多个参数
- inputParamterName: 输入参数名称
  - description: 输入参数描述
  - required: 是否必填，是一个 bool 变量
  - default: 默认值
outputs: 定义输出参数集合，可以包含多个参数
- outputParamterName: 输出参数名称
  - description: 输出参数描述
runs: 配置 action 代码的路径和用于执行代码的应用程序
branding: 在 GitHub Marketplace 中显示的图标样式
- icon: 图标名称，须从Feather 中选取
- color: 图标颜色，可以使以下 8 种颜色：white、yellow、blue、green、orange、red、purple 或 gray-dark

定义输入参数

inputs 对象定义了 action 所依赖的输入参数，根据官方文档中的描述，输入参数会被存储到名为 INPUT_<VARIABLE_NAME> 的环境变量中，参数名称会被转换为大写，空格替换为 _ 字符，action 代码中可以读取该环境变量从而得到输入参数的值

例如，inputs 中所定义的 inputParamterName输入参数的值，会被存储到名为 INPUT_INPUTPARAMTERNAME 的环境变量中

但是，尽管官方文档中这样说，但在使用的过程中却遇到了坑。所定义的输入参数并不能够直接通过读取该环境变量取值，事实上通过在执行过程中打印日志，在环境变量中并没有发现输入参数

因此，解决办法是手动将其定义到 env 对象中，这样在脚本中就可以通过 $INPUT_<PARAMTER_NAME> 获取到输入变量的值了

steps:- name: Run scriptshell: bashrun: $GITHUB_ACTION_PATH/script.shenv:INPUT_KEY: ${
    {
     inputs.key }}INPUT_TITLE: ${
    {
     inputs.title }}INPUT_BODY: ${
    {
     inputs.body }}INPUT_SOUND: ${
    {
     inputs.sound }}INPUT_ISARCHIVE: ${
    {
     inputs.isArchive }}INPUT_URL: ${
    {
     inputs.url }}INPUT_AUTOMATICALLYCOPY: ${
    {
     inputs.automaticallyCopy }}INPUT_COPY: ${
    {
     inputs.copy }}

对于不方便公开的输入参数，例如密码、私钥等，可以先保存至仓库的 Secrets 中，传入时通过以下方式传入

- name: Push notificationsuses: shink/bark-action@v1with:key: ${
    {
     secrets.KEY }}

定义运行步骤

action 支持 JavaScript、Docker 和组合运行三种运行步骤方式

JavaScript 运行方式

示例：

runs:using: 'node12'main: 'main.js'

可参考官方文档

Docker 运行方式

runs:using: 'docker'image: 'docker://debian:stretch-slim'

可参考官方文档

组合运行方式

示例：

runs:using: "composite"steps:- run: ${
    {
     github.action_path }}/test/script.shshell: bash

组合运行方式支持各类脚本，更加灵活易用

using: 组合运行方式必须设置为 composite
steps: 运行步骤集合，可以包含多个步骤，每个步骤顺序执行
- name: 步骤名称
- id: 该步骤的唯一标识
- shell: 运行方式，支持 using-a-specific-shell 中所列的所有 shell，常用的有 bash、python
- run: 脚本文件路径
- env: 仅用于该步骤的环境变量
- working-directory: 工作目录路径

示例

shink/bark-action 中的 action.yml示例：

name: 'Bark Action'
description: 'An action for bark'
author: Ji Yuanhao <jiyuanhao1997@gmail.com>
branding:icon: 'message-circle'color: 'red'
inputs:key:description: Secret keyrequired: truetitle:description: Message titlerequired: falsebody:description: Message bodyrequired: falsesound:description: Message soundrequired: falseisArchive:description: Whether to archive this messagerequired: falseurl:description: URL to redirectrequired: falseautomaticallyCopy:description: Whether to copy this message automaticallyrequired: falsecopy:description: Content copied to clipboardrequired: false
runs:using: "composite"steps:- name: Run scriptshell: bashrun: $GITHUB_ACTION_PATH/script.shenv:INPUT_KEY: ${
    {
     inputs.key }}INPUT_TITLE: ${
    {
     inputs.title }}INPUT_BODY: ${
    {
     inputs.body }}INPUT_SOUND: ${
    {
     inputs.sound }}INPUT_ISARCHIVE: ${
    {
     inputs.isArchive }}INPUT_URL: ${
    {
     inputs.url }}INPUT_AUTOMATICALLYCOPY: ${
    {
     inputs.automaticallyCopy }}INPUT_COPY: ${
    {
     inputs.copy }}

至此，编写好 action.yml 文件后，在当前仓库中的 .github/workflows/<CI_NAME>.yml 中就可以通过以下方式使用自定义的 action 了

- name: Run my actionuses: ./

例如，在 shink/bark-action 的 .github/workflows/push-notification.yml 中：

name: 'Push Notifications to Bark'on: repository_dispatch:workflow_dispatch:jobs:job:name: Push notification jobruns-on: ubuntu-lateststeps:- name: Checkoutuses: actions/checkout@v2- name: Push notificationsuses: ./with:key: ${
    {
     secrets.KEY }}title: Message titlebody: Message bodysound: alarmisArchive: 1url: https://yuanhaoji.comautomaticallyCopy: 1copy: Content copied to clipboard

发布至 GitHub Marketplace

编写好 action.yml 及运行代码后，就可以发布至 GitHub Marketplace 供他人使用了

如果仓库根目录下有 action.yml 或 action.yaml 文件，仓库页面上方就会提示是否需要发布

点击 Draft a release 按钮，进入发布页面，勾选 Publish this Action to the GitHub Marketplace

会自动检测 action.yml 文件中是否包含必填字段，以及仓库中是否有 README.md 文档

填写 Primary Category 和 Another Category，为 action 选择类别

接下来是 Tag，输入 Tag version，建议使用 v1、v1.2.3 等作为标签版本名称

最后是 Release，填写 Release title 和 Release description，点击 Publish release 后即可完成发布

发布完成后，即可在 GitHub Marketplace 页面看到自己发布的 action

参考

Github action 的开发到发布

Metadata syntax for GitHub Actions