## 前言

上一篇文章你学会了用别人的 Action，本篇教你写自己的 Action——把重复的步骤封装成可复用的组件，发布到 Marketplace 让全世界的项目都能用。这是 GitHub Actions 生态的核心能力。

---

## 一、Action 的三种类型

| 类型 | 实现方式 | 适用场景 | 复杂度 |
|------|---------|---------|--------|
| Composite Action | YAML 组合 | 组合多个步骤为一个 Action | 低 |
| JavaScript Action | TypeScript/JS | 需要自定义逻辑和 UI 交互 | 中 |
| Docker Action | Dockerfile | 需要特定运行环境 | 中 |

> **培训要点**：90% 的场景用 Composite Action 就够了——不需要写代码，纯 YAML 组合。先学这种。

---

## 二、Composite Action 开发

### 创建 Action 仓库

```
my-deploy-action/
├── action.yml       # Action 定义文件
├── README.md
└── scripts/
    └── deploy.sh
```

### action.yml 核心配置

```yaml
# action.yml
name: 'Deploy to Kubernetes'
description: 'Deploy a Docker image to Kubernetes with health check and auto-rollback'
author: 'Your Name'

# 定义输入参数
inputs:
  image:
    description: 'Docker image to deploy'
    required: true
  namespace:
    description: 'Kubernetes namespace'
    required: false
    default: 'default'
  deployment-name:
    description: 'Kubernetes Deployment name'
    required: true
  timeout:
    description: 'Rollout timeout in seconds'
    required: false
    default: '180'

# 定义输出
outputs:
  status:
    description: 'Deployment status (success/failed)'
    value: ${{ steps.deploy.outputs.status }}

runs:
  using: composite
  steps:
    # 第一步：部署
    - name: Deploy
      id: deploy
      shell: bash
      env:
        IMAGE: ${{ inputs.image }}
        NAMESPACE: ${{ inputs.namespace }}
        DEPLOYMENT: ${{ inputs.deployment-name }}
        TIMEOUT: ${{ inputs.timeout }}
        KUBECONFIG: ${{ env.KUBECONFIG }}
      run: |
        # 更新镜像
        kubectl set image deployment/${DEPLOYMENT} \
          app=${IMAGE} -n ${NAMESPACE}
        
        # 等待滚动更新完成
        if kubectl rollout status deployment/${DEPLOYMENT} \
          -n ${NAMESPACE} --timeout=${TIMEOUT}s; then
          echo "status=success" >> $GITHUB_OUTPUT
        else
          echo "status=failed" >> $GITHUB_OUTPUT
          # 自动回滚
          kubectl rollout undo deployment/${DEPLOYMENT} -n ${NAMESPACE}
          exit 1
        fi

    # 第二步：健康检查
    - name: Health check
      if: ${{ steps.deploy.outputs.status == 'success' }}
      shell: bash
      env:
        NAMESPACE: ${{ inputs.namespace }}
        DEPLOYMENT: ${{ inputs.deployment-name }}
      run: |
        for i in $(seq 1 12); do
          READY=$(kubectl get deployment ${DEPLOYMENT} -n ${NAMESPACE} \
            -o jsonpath='{.status.readyReplicas}')
          DESIRED=$(kubectl get deployment ${DEPLOYMENT} -n ${NAMESPACE} \
            -o jsonpath='{.status.replicas}')
          if [ "$READY" = "$DESIRED" ]; then
            echo "All pods ready ($READY/$DESIRED)"
            exit 0
          fi
          sleep 10
        done
        echo "Health check failed"
        exit 1
```

### 使用自己的 Action

```yaml
# 在其他项目的 Workflow 中使用
jobs:
  deploy:
    runs-on: [self-hosted, k8s]
    steps:
      - uses: actions/checkout@v4
      
      # 使用本地 Action（同一仓库内）
      - uses: ./.github/actions/deploy
        with:
          image: ghcr.io/myorg/myapp:latest
          namespace: production
          deployment-name: myapp
      
      # 使用其他仓库的 Action
      - uses: myorg/my-deploy-action@v1
        with:
          image: ghcr.io/myorg/myapp:${{ github.sha }}
          namespace: production
          deployment-name: myapp
          timeout: '300'
```

---

## 三、JavaScript Action 开发

### 项目结构

```
js-action/
├── action.yml
├── package.json
├── tsconfig.json
├── src/
│   └── main.ts
├── dist/
│   └── index.js    # 编译后的 JS
└── .eslintrc.json
```

### action.yml

```yaml
name: 'PR Comment Bot'
description: 'Add a comment to a PR with build status and test results'

inputs:
  pr-number:
    description: 'PR number'
    required: true
  status:
    description: 'Build status (success/failure)'
    required: true
  report-path:
    description: 'Path to test report'
    required: false

runs:
  using: node20
  main: dist/index.js
```

### TypeScript 实现

```typescript
// src/main.ts
import * as core from '@actions/core';
import * as github from '@actions/github';
import * as fs from 'fs';

async function run(): Promise<void> {
  try {
    const prNumber = core.getInput('pr-number');
    const status = core.getInput('status');
    const reportPath = core.getInput('report-path');
    
    const token = core.getInput('github-token') || process.env.GITHUB_TOKEN;
    const octokit = github.getOctokit(token);
    
    // 读取测试报告
    let reportSummary = 'No report available';
    if (reportPath && fs.existsSync(reportPath)) {
      const report = fs.readFileSync(reportPath, 'utf-8');
      const parsed = JSON.parse(report);
      reportSummary = `Tests: ${parsed.total}, Passed: ${parsed.passed}, Failed: ${parsed.failed}`;
    }
    
    // 构建评论内容
    const statusEmoji = status === 'success' ? '✅' : '❌';
    const body = [
      `## ${statusEmoji} Build ${status}`,
      ``,
      `**Report:** ${reportSummary}`,
      ``,
      `**Commit:** ${github.context.sha.substring(0, 7)}`,
    ].join('\n');
    
    // 发表评论到 PR
    await octokit.rest.issues.createComment({
      ...github.context.repo,
      issue_number: parseInt(prNumber),
      body: body,
    });
    
    core.setOutput('comment-url', `PR #${prNumber}`);
    
  } catch (error) {
    core.setFailed((error as Error).message);
  }
}

run();
```

### package.json

```json
{
  "name": "pr-comment-bot",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "ncc build src/main.ts -o dist --source-map",
    "lint": "eslint src/**/*.ts"
  },
  "dependencies": {
    "@actions/core": "^1.10.0",
    "@actions/github": "^6.0.0"
  },
  "devDependencies": {
    "@vercel/ncc": "^0.38.0",
    "typescript": "^5.3.0"
  }
}
```

### 编译

```bash
npm install
npm run build  # 用 ncc 打包成单文件
```

> **踩坑提示**：JavaScript Action 必须用 `@vercel/ncc` 打包成单文件，不能直接引用 node_modules。因为 GitHub Actions 运行时只下载你的仓库，不会自动 npm install。

---

## 四、Action 版本管理

### Tag 策略

```
# 语义化版本 Tag
v1         → 指向最新的 1.x.x 版本（自动跟随 minor/patch 更新）
v1.0       → 指向最新的 1.0.x 版本
v1.0.0     → 固定版本

# 使用时：
- uses: myorg/my-action@v1        # 自动获取最新 1.x.x
- uses: myorg/my-action@v1.2      # 自动获取最新 1.2.x
- uses: myorg/my-action@v1.2.3    # 固定版本
- uses: myorg/my-action@main      # 跟随主分支（不推荐生产用）
```

### 发布到 GitHub Marketplace

1. 在 Action 仓库 → Releases → Create a new release
2. 选择 "Publish this Action to the GitHub Marketplace"
3. 填写 Category（如 Continuous Integration）
4. 发布

发布后，用户可以在 GitHub Marketplace 搜索到你的 Action：

```yaml
# 用户使用
- uses: your-name/my-deploy-action@v1
  with:
    image: myapp:latest
```

### 版本发布的最佳实践

```yaml
# .github/workflows/release.yml
name: Release

on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # 自动创建/更新 major version tag (v1)
      - name: Update major tag
        uses: actions/publish-action@v0.3
        with:
          source-tag: ${{ github.ref_name }}  # 如 v1.2.3
```

---

## 五、Reusable Workflow（可复用工作流）

### 什么是 Reusable Workflow

Composite Action 封装的是步骤，Reusable Workflow 封装的是整个 Job——可以跨仓库复用完整的 CI/CD 流程。

### 定义 Reusable Workflow

```yaml
# .github/workflows/reusable-build.yml
name: Reusable Build

on:
  workflow_call:
    inputs:
      java-version:
        type: string
        required: false
        default: '17'
      run-tests:
        type: boolean
        required: false
        default: true
    secrets:
      sonar-token:
        required: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ inputs.java-version }}
          distribution: temurin
          cache: maven
      - run: mvn clean package -DskipTests
      - run: mvn test
        if: ${{ inputs.run-tests }}
      - uses: actions/upload-artifact@v4
        with:
          name: app-jar
          path: target/*.jar
```

### 调用 Reusable Workflow

```yaml
# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  # 调用可复用工作流
  build:
    uses: myorg/ci-templates/.github/workflows/reusable-build.yml@v1
    with:
      java-version: '21'
      run-tests: true
    secrets:
      sonar-token: ${{ secrets.SONAR_TOKEN }}
  
  # 调用后继续自己的步骤
  deploy:
    needs: build
    runs-on: [self-hosted]
    steps:
      - uses: actions/download-artifact@v4
      - run: ./deploy.sh
```

### 组织级模板仓库

创建一个专门的 CI 模板仓库：

```
ci-templates/
├── .github/workflows/
│   ├── reusable-build-java.yml     # Java 构建模板
│   ├── reusable-build-go.yml       # Go 构建模板
│   ├── reusable-build-node.yml     # Node 构建模板
│   ├── reusable-deploy-k8s.yml     # K8s 部署模板
│   └── reusable-security-scan.yml  # 安全扫描模板
└── README.md
```

所有项目只需几行调用：

```yaml
# 项目的 .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  build:
    uses: myorg/ci-templates/.github/workflows/reusable-build-java.yml@v1
    with:
      java-version: '17'
  
  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    uses: myorg/ci-templates/.github/workflows/reusable-deploy-k8s.yml@v1
    with:
      namespace: production
    secrets:
      kubeconfig: ${{ secrets.KUBECONFIG_PROD }}
```

> **培训要点**：Reusable Workflow 比 Composite Action 更强大——它可以定义完整的 Job（含 runs-on、services、environment），而 Composite Action 只是 Step 级别的复用。对于组织级的 CI/CD 标准化，用 Reusable Workflow 建立模板仓库。

---

## 六、本篇要点回顾

1. 三种 Action 类型：Composite（YAML 组合，最简单）、JavaScript（自定义逻辑）、Docker（特定环境）
2. Composite Action 用 `using: composite` 定义，通过 `inputs` 接收参数
3. JavaScript Action 必须用 `@vercel/ncc` 打包成单文件
4. 版本管理用语义化 Tag：`@v1` 自动跟随、`@v1.2.3` 固定版本
5. Reusable Workflow 封装整个 Job，适合组织级 CI/CD 标准化

**下一篇预告**：进入 CI/CD 进阶篇，下一篇：《安全实践：密钥管理、镜像签名与供应链安全》。

上一篇文章你学会了用别人的 Action，本篇教你写自己的 Action——把重复的步骤封装成可复用的组件，发布到 Marketplace 让全世界的项目都能用。这是 GitHub Actions 生态的核心能力。

【CI/CD·Actions篇】进阶实战：复合 Action 开发与 Marketplace 利用

研发部经理

开发工具

后端

运维

本文详解GitHub Actions自定义开发：从Composite Action的YAML组合、JavaScript Action的TypeScript实现到Docker容器化，覆盖三种Action类型选择、版本管理策略、Marketplace发布流程及Reusable Workflow组织级复用方案，助你封装可复用CI/CD组件。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文详解GitHub Actions自定义开发：从Composite Action的YAML组合、JavaScript Action的TypeScript实现到Docker容器化，覆盖三种Action类型选择、版本管理策略、Marketplace发布流程及Reusable Workflow组织级复用方案，助你封装可复用...

【CI/CD·Actions篇】进阶实战：复合 Action 开发与 Marketplace 利用-腾讯云开发者社区-腾讯云

【CI/CD·Actions篇】进阶实战：复合 Action 开发与 Marketplace 利用

【CI/CD·Actions篇】进阶实战：复合 Action 开发与 Marketplace 利用

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐