# Web 项目发布构建 Action

[![GitHub](https://img.shields.io/badge/github-actions-blue.svg)](https://github.com/features/actions)

自动化 Web 项目发布流程的 GitHub Action，包括版本发布、Docker 镜像构建和推送等完整的 CI/CD 流程。

## 功能特性

- 🚀 **自动化发布**: 支持 `release-it` 工具进行版本管理和发布
- 🐳 **Docker 集成**: 自动构建和推送 Docker 镜像到私有仓库
- 🏷️ **灵活标签**: 支持自定义 Docker 标签，自动生成版本标签
- 📊 **Sentry 集成**: 可选的 Sentry 错误监控集成
- 🔧 **高度可配置**: 丰富的输入参数满足不同项目需求
- ✅ **参数验证**: 自动验证必需参数和文件存在性

## 快速开始

### 基础用法

```yaml
- name: 发布Web项目
  uses: actions/xgj/release-web@main
  with:
    gitea-token: ${{ secrets.GITEA_TOKEN }}
```

### 使用环境变量

```yaml
- name: 发布Web项目
  uses: actions/xgj/release-web@main
  with:
    gitea-token: ${{ secrets.GITEA_TOKEN }}
  env:
    # 🌍 可以传递任意数量的环境变量给发布命令
    APP_ENV: production
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_DSN: ${{ vars.SENTRY_DSN }}
    SENTRY_VITE: true
    BUILD_NUMBER: ${{ github.run_number }}
    CUSTOM_CONFIG: "your-value"
    FEATURE_FLAG: ${{ github.ref == 'refs/heads/main' }}
    # ... 更多任意环境变量
```

### 完整示例

```yaml
- name: 发布Web项目
  uses: actions/xgj/release-web@main
  with:
    gitea-token: ${{ secrets.GITEA_TOKEN }}
    app-env: "production"
    sentry-auth-token: ${{ secrets.SENTRY_AUTH_TOKEN }}
    sentry-dsn: ${{ vars.SENTRY_DSN }}
    enable-sentry: "true"
    docker-registry: "docker-registry.bjxgj.com"
    dockerfile-path: "./container/prod/Dockerfile"
    docker-tags: |
      stable
      v2024
```

## 输入参数

| 参数名                | 描述                      | 必需 | 默认值                            |
| --------------------- | ------------------------- | ---- | --------------------------------- |
| `gitea-token`         | Gitea 访问令牌            | ✅   | -                                 |
| `app-env`             | 应用环境                  | ❌   | `production`                      |
| `sentry-auth-token`   | Sentry 认证令牌           | ❌   | -                                 |
| `sentry-dsn`          | Sentry DSN 配置           | ❌   | -                                 |
| `enable-sentry`       | 是否启用 Sentry           | ❌   | `false`                           |
| `release-command`     | 发布命令                  | ❌   | `npm run release -- --release -V` |
| `docker-registry`     | Docker 仓库地址           | ❌   | `docker-registry.bjxgj.com`       |
| `docker-context`      | Docker 构建上下文路径     | ❌   | `.`                               |
| `dockerfile-path`     | Dockerfile 路径           | ❌   | `./container/dev/Dockerfile`      |
| `docker-tags`         | 额外的 Docker 标签        | ❌   | -                                 |
| `enable-docker-build` | 是否执行 Docker 构建      | ❌   | `true`                            |
| `node-debug`          | 是否启用 Node.js 调试模式 | ❌   | `false`                           |

## 环境变量支持

Action 支持通过 `env` 传递**任意数量**的环境变量给发布命令，这些环境变量会自动传递给 `npm run release` 或其他发布命令：

```yaml
- uses: actions/xgj/release-web@main
  with:
    gitea-token: ${{ secrets.GITEA_TOKEN }}
  env:
    # 🌍 任意环境变量都会自动传递给发布命令
    APP_ENV: production
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_TOKEN }}
    CUSTOM_VAR: "your-value"
    BUILD_NUMBER: ${{ github.run_number }}
    FEATURE_FLAG: ${{ github.ref == 'refs/heads/main' }}
    # ... 更多任意变量
```

### 常用环境变量示例

| 环境变量名          | 描述             | 示例值                        |
| ------------------- | ---------------- | ----------------------------- |
| `APP_ENV`           | 应用环境         | `production`                  |
| `SENTRY_AUTH_TOKEN` | Sentry 认证令牌  | `${{ secrets.SENTRY_TOKEN }}` |
| `SENTRY_DSN`        | Sentry DSN 配置  | `${{ vars.SENTRY_DSN }}`      |
| `SENTRY_VITE`       | 是否启用 Sentry  | `true`                        |
| `NODE_DEBUG`        | Node.js 调试模式 | `release-it:*`                |
| `BUILD_NUMBER`      | 构建编号         | `${{ github.run_number }}`    |

## 输出参数

| 参数名                | 描述                     |
| --------------------- | ------------------------ |
| `version`             | 发布的版本号             |
| `version-with-dash`   | 版本号（点号替换为横线） |
| `docker-image-digest` | Docker 镜像摘要          |
| `docker-image-tags`   | Docker 镜像标签列表      |

## 使用场景

### 1. 基础发布流程

适用于简单的 Web 项目发布：

```yaml
steps:
  - uses: actions/checkout@v4

  - name: 设置环境
    uses: actions/xgj/setup-env@main
    with:
      docker-password: ${{ secrets.DOCKER_PASSWORD }}

  - name: 安装依赖
    uses: actions/xgj/npm-install@main

  - name: 发布项目
    uses: actions/xgj/release-web@main
    with:
      gitea-token: ${{ secrets.GITEA_TOKEN }}
```

### 2. 完整 CI/CD 流程

包含完整的构建、测试、发布流程：

```yaml
steps:
  - uses: actions/checkout@v4

  - name: 设置构建环境
    uses: actions/xgj/setup-env@main
    with:
      docker-password: ${{ secrets.DOCKER_PASSWORD }}
      kube-config: ${{ secrets.KUBE_CONFIG }}

  - name: 安装依赖
    uses: actions/xgj/npm-install@main
    with:
      package-manager: "pnpm"

  - name: 运行测试
    run: npm run test

  - name: 发布构建
    id: release
    uses: actions/xgj/release-web@main
    with:
      gitea-token: ${{ secrets.GITEA_TOKEN }}
      app-env: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
      sentry-auth-token: ${{ secrets.SENTRY_AUTH_TOKEN }}
      sentry-dsn: ${{ vars.SENTRY_DSN }}
      enable-sentry: "true"
      dockerfile-path: "./Dockerfile"
      docker-tags: |
        ${{ github.sha }}
        ${{ github.ref_name }}

  - name: 部署到Kubernetes
    run: |
      kubectl set image deployment/web-app web-app=docker-registry.bjxgj.com/${{ github.event.repository.name }}:${{ steps.release.outputs.version }}
```

### 3. 多环境发布

支持不同环境的差异化配置：

```yaml
strategy:
  matrix:
    environment: [staging, production]
    include:
      - environment: staging
        dockerfile: "./container/dev/Dockerfile"
        app-env: "staging"
      - environment: production
        dockerfile: "./container/prod/Dockerfile"
        app-env: "production"

steps:
  - name: 发布到 ${{ matrix.environment }}
    uses: actions/xgj/release-web@main
    with:
      gitea-token: ${{ secrets.GITEA_TOKEN }}
      app-env: ${{ matrix.app-env }}
      dockerfile-path: ${{ matrix.dockerfile }}
      docker-tags: ${{ matrix.environment }}
```

## 工作流程

1. **参数验证**: 检查必需参数和文件是否存在
2. **发布构建**: 执行 `release-it` 命令进行版本发布
3. **获取版本**: 从 `/tmp/last-version` 读取新版本号
4. **准备标签**: 生成 Docker 镜像标签列表
5. **Docker 构建**: 构建并推送 Docker 镜像（可选）
6. **发布总结**: 输出发布信息和结果

## 依赖要求

### 项目要求

- 包含 `package.json` 文件
- 配置了 `release-it` 工具
- 包含发布脚本（如 `npm run release`）
- Docker 构建需要有效的 `Dockerfile`

### 环境依赖

- Node.js 环境
- npm/pnpm/yarn 包管理器
- Docker（如果启用 Docker 构建）
- 配置好的 Docker 仓库访问权限

## 配置示例

### release-it 配置

确保项目中有类似的 `.release-it.js` 配置：

```javascript
module.exports = {
  hooks: {
    "before:release": [
      "echo '${version}' > /tmp/last-version",
      "npm run build",
    ],
  },
  git: {
    tagName: "v${version}",
    commitMessage: "chore: released version v${version} [no ci]",
  },
  npm: {
    publish: false,
  },
};
```

### Docker 多阶段构建

推荐使用多阶段构建优化镜像大小：

```dockerfile
# 构建阶段
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# 运行阶段
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY dist ./dist
EXPOSE 3000
CMD ["npm", "start"]
```

## 错误处理

Action 会在以下情况报错并退出：

- 缺少必需的 `gitea-token` 参数
- 指定的 `Dockerfile` 不存在
- `/tmp/last-version` 文件不存在（发布命令未正确执行）
- Docker 构建失败

## 安全注意事项

- 🔒 始终通过 `secrets` 传递敏感令牌
- 🔍 定期检查和轮换访问令牌
- 📋 限制 Docker 仓库访问权限
- 🚫 避免在日志中暴露敏感信息

## 故障排除

### 常见问题

**Q: 版本文件不存在错误**

```
❌ 错误: 版本文件 /tmp/last-version 不存在
```

A: 检查 `release-it` 配置是否包含创建版本文件的 hook：

```javascript
hooks: {
  'before:release': ['echo \'${version}\' > /tmp/last-version']
}
```

**Q: Docker 构建失败**

A: 检查：

1. Dockerfile 路径是否正确
2. Docker 仓库是否已登录（使用 `actions/xgj/setup-env` action）
3. 构建上下文是否包含必需文件

**Q: Gitea Token 权限不足**

A: 确保 token 具有以下权限：

- Repository 写权限
- Releases 创建权限

### 调试模式

启用详细调试信息：

```yaml
- uses: actions/xgj/release-web@main
  with:
    gitea-token: ${{ secrets.GITEA_TOKEN }}
    node-debug: "true"
```

## 更新日志

查看 [Releases](https://github.com/your-org/actions/releases) 获取详细的更新历史。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个 Action！

## 许可证

MIT License - 详见 [LICENSE](../LICENSE) 文件。