action.json是什么文件

action.json：GitHub Actions 工作流的“身份证”与“说明书”

在 GitHub Actions 的自动化世界中，action.yml（或 action.json）文件扮演着至关重要的角色，它就像是自定义 Action 的“身份证”和“说明书”，清晰地定义了这个 Action 是什么、能做什么、需要什么参数、以及如何使用。action.json 是一个用于描述 GitHub Action 元数据和接口的 JSON 格式配置文件，是创建和分享可复用 Action 组件的核心。

action.json 文件的核心作用

身份标识：文件本身的存在及其内容，向 GitHub 平台表明这是一个可被识别和使用的 GitHub Action。
元数据描述：提供了 Action 的基本信息，如名称、描述、作者、版本、图标等，帮助用户快速了解 Action 的用途和背景。
接口定义：明确规定了 Action 的输入参数（inputs）、输出参数（outputs），以及执行环境（runs）的要求，这是 Action 与其他工作流步骤交互的基础。
规范与兼容性：遵循 GitHub 官方定义的 JSON Schema，确保 Action 能够被 GitHub 正确解析和执行，保证不同 Action 之间的兼容性。

action.json 文件的关键组成部分

一个典型的 action.json 文件包含以下主要字段（注意：GitHub 官方推荐使用 action.yml，因为它更简洁且支持 YAML 特性，但 action.json 也是完全支持的，尤其在 JavaScript/Node.js 生态中更为常见）：

name (必需)：Action 的名称,通常简短且具有描述性。
description (必需)：Action 的详细描述,说明其主要功能和用途。
author (可选)：Action 的作者信息,可以是用户名或组织名。
version (可选)：Action 的版本号，遵循语义化版本规范（如 1.0.0）。
runs (必需)：定义 Action 的执行方式，这是核心部分。
- using (必需)：指定 Action 的运行方式，常见值有：
  - node12：使用 Node.js 12 运行。
  - node16：使用 Node.js 16 运行。
  - docker：使用 Docker 容器运行。
  - composite：使用复合命令运行（较新特性）。
- main (当 using 为 node12, node16, composite 时必需)：指向执行脚本的路径，通常是 index.js 或 entrypoint.sh。
- image (当 using 为 docker 时必需)：指定 Docker 镜像的名称和标签，如 node:16-buster。
- pre (可选，composite 时使用)：执行主命令前要运行的步骤。
- post (可选，composite 时使用)：执行主命令后要运行的步骤。
inputs (可选)：定义 Action 接收的参数。
- 每个输入是一个对象，包含：
  - description：参数的描述。
  - required：布尔值,表示该参数是否必需。
  - default：参数的默认值（可选）。
  - type：参数的类型，如 string, boolean, number, choice 等。
outputs (可选)：定义 Action 输出的参数，供后续步骤使用。
- 每个输出是一个对象，通常包含 description 和 value（或通过脚本设置）。
branding (可选)：定义 Action 在 GitHub UI 中显示的品牌颜色，如 color 和 icon,提升识别度。

示例：一个简单的 action.json 文件

假设我们创建一个名为 hello-world-log 的 Action，它接收一个 name 输入，并打印一条个性化的问候消息，同时输出 greeting 字符串。

{
  "name": "Hello World Log Action",
  "description": "Logs a personalized hello world message and outputs a greeting.",
  "author": "YourGitHubUsername",
  "version": "1.0.0",
  "runs": {
    "using": "node16",
    "main": "index.js"
  },
  "inputs": {
    "name": {
      "description": "The name to greet",
      "required": true,
      "default": "World"
    }
  },
  "outputs": {
    "greeting": {
      "description": "The generated greeting message"
    }
  },
  "branding": {
    "color": "gray-dark",
    "icon": "smiley"
  }
}

对应的 index.js 文件会读取 name 输入，打印日志，并设置 greeting 输出。

action.json 与 action.yml 的选择

虽然 action.json 完全可用，但 GitHub 官方更推荐使用 action.yml（YAML 格式）,主要原因包括：

可读性：YAML 通常比 JSON 更易读,尤其是在配置复杂时。
简洁性：YAML 对某些数据结构的表示更简洁。
官方偏好：GitHub 的文档和示例多以 action.yml 为主。

如果你的 Action 项目是基于 JavaScript/TypeScript 的，使用 action.json 可能与项目结构更为一致，且可以直接通过 JSON.parse 等方式处理。

action.json 文件是 GitHub Actions 生态中不可或缺的一环，它为自定义 Action 提供了标准化的描述和接口规范，无论是作为开发者创建可复用的自动化步骤，还是作为使用者理解和使用第三方 Action，action.json 都扮演着信息桥梁和契约的角色，其结构和作用，能让你更高效地利用和贡献于 GitHub Actions 的强大功能。