action-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Action Builder

Action 构建指南

Build custom GitHub Actions for reusable workflow logic.

构建用于工作流逻辑复用的自定义GitHub Actions。

Quick Start

快速开始

Choose action type based on requirements:

Composite: Combine multiple workflow steps (simplest, no code)
Docker: Run containerized logic (any language, slower startup)
JavaScript: Fast execution, Node.js required

根据需求选择Action类型：

Composite：组合多个工作流步骤（最简单，无需代码）
Docker：运行容器化逻辑（支持任意编程语言，启动速度较慢）
JavaScript：执行速度快，需要Node.js环境

Instructions

操作步骤

Step 1: Choose Action Type

步骤1：选择Action类型

Use Composite when:

Combining existing actions and shell commands
No custom code needed
Fast execution required
Example: Setup environment with multiple tools

Use Docker when:

Need specific runtime environment
Using non-JavaScript languages
Complex dependencies
Example: Custom linting tool, data processing

Use JavaScript when:

Need programmatic control
Fast startup time critical
Interacting with GitHub API
Example: Issue labeler, PR validator

选择Composite类型的场景：

组合现有Action和Shell命令
无需自定义代码
需要快速执行
示例：使用多个工具搭建环境

选择Docker类型的场景：

需要特定的运行时环境
使用非JavaScript编程语言
存在复杂依赖
示例：自定义代码检查工具、数据处理任务

选择JavaScript类型的场景：

需要程序化控制
对启动速度要求较高
需要与GitHub API交互
示例：Issue标签器、PR验证工具

Step 2: Create Action Structure

步骤2：创建Action目录结构

All action types need:

action-name/
├── action.yml          # Action metadata
├── README.md           # Documentation
└── [implementation]    # Type-specific files

所有类型的Action都需要以下结构：

action-name/
├── action.yml          # Action元数据文件
├── README.md           # 文档说明
└── [implementation]    # 对应类型的实现文件

Step 3: Define action.yml

步骤3：定义action.yml文件

Required fields:

yaml

name: 'Action Name'
description: 'What the action does'
author: 'Your Name'

inputs:
  input-name:
    description: 'Input description'
    required: true
    default: 'default-value'

outputs:
  output-name:
    description: 'Output description'
    value: ${{ steps.step-id.outputs.output-name }}

runs:
  using: 'composite|docker|node16'
  # Type-specific configuration

必填字段：

yaml

name: 'Action Name'
description: 'What the action does'
author: 'Your Name'

inputs:
  input-name:
    description: 'Input description'
    required: true
    default: 'default-value'

outputs:
  output-name:
    description: 'Output description'
    value: ${{ steps.step-id.outputs.output-name }}

runs:
  using: 'composite|docker|node16'
  # 对应类型的配置内容

Step 4: Implement Action Logic

步骤4：实现Action逻辑

For Composite Actions:

yaml

runs:
  using: 'composite'
  steps:
    - name: Step name
      run: echo "Command"
      shell: bash
    - uses: actions/checkout@v3

For Docker Actions:

yaml

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.input-name }}

For JavaScript Actions:

yaml

runs:
  using: 'node16'
  main: 'dist/index.js'

对于Composite类型Action：

yaml

runs:
  using: 'composite'
  steps:
    - name: Step name
      run: echo "Command"
      shell: bash
    - uses: actions/checkout@v3

对于Docker类型Action：

yaml

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.input-name }}

对于JavaScript类型Action：

yaml

runs:
  using: 'node16'
  main: 'dist/index.js'

Step 5: Test Action Locally

步骤5：本地测试Action

Test in workflow:

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ./  # Test local action
        with:
          input-name: 'test-value'

在工作流中测试：

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ./  # 测试本地Action
        with:
          input-name: 'test-value'

Step 6: Version and Publish

步骤6：版本管理与发布

Versioning:

Use semantic versioning (v1.0.0)
Create Git tags for releases
Maintain major version tags (v1, v2)

Publishing:

Push to GitHub repository
Create release with tag
Add to GitHub Marketplace (optional)

版本管理：

使用语义化版本（如v1.0.0）
为版本创建Git标签
维护主版本标签（如v1、v2）

发布流程：

推送代码至GitHub仓库
创建带标签的版本发布
（可选）发布至GitHub Marketplace

Common Patterns

常见模式

Input Validation

输入参数验证

yaml

inputs:
  environment:
    description: 'Deployment environment'
    required: true
  region:
    description: 'AWS region'
    required: false
    default: 'us-east-1'

yaml

inputs:
  environment:
    description: 'Deployment environment'
    required: true
  region:
    description: 'AWS region'
    required: false
    default: 'us-east-1'

Output Setting

输出参数设置

Composite:

bash

echo "output-name=value" >> $GITHUB_OUTPUT

JavaScript:

javascript

core.setOutput('output-name', 'value');

Composite类型：

bash

echo "output-name=value" >> $GITHUB_OUTPUT

JavaScript类型：

javascript

core.setOutput('output-name', 'value');

Error Handling

错误处理

Composite:

bash

if [ $? -ne 0 ]; then
  echo "::error::Operation failed"
  exit 1
fi

JavaScript:

javascript

try {
  // Action logic
} catch (error) {
  core.setFailed(error.message);
}

Composite类型：

bash

if [ $? -ne 0 ]; then
  echo "::error::Operation failed"
  exit 1
fi

JavaScript类型：

javascript

try {
  // Action logic
} catch (error) {
  core.setFailed(error.message);
}

Advanced

进阶内容

For detailed implementation guides:

Composite Actions - Multi-step workflows
Docker Actions - Containerized actions
Inputs and Outputs - Data handling patterns

如需详细实现指南，请参考：

Composite Actions - 多步骤工作流
Docker Actions - 容器化Action
Inputs and Outputs - 数据处理模式

Troubleshooting

故障排查

Action not found:

Verify action.yml exists in repository root
Check action path in workflow (uses: owner/repo@version)

Inputs not working:

Confirm input names match action.yml
Check required vs. optional inputs
Verify default values

Outputs not available:

Ensure output is set before job completes
Check step ID matches output reference
Verify output syntax (${{ steps.id.outputs.name }})

Action未找到：

确认action.yml文件存在于仓库根目录
检查工作流中的Action路径（格式：uses: owner/repo@version）

输入参数不生效：

确认输入参数名称与action.yml中的定义一致
检查参数是必填还是可选
验证默认值是否正确

输出参数不可用：

确保输出参数在作业完成前已设置
检查步骤ID与输出引用是否匹配
验证输出语法是否正确（格式：${{ steps.id.outputs.name }}）