Release It! Gitea Plugin

English | 中文

一个用于 release-it 的 Gitea 插件，支持自动创建 Gitea 发布并上传附件。

功能特性

• ✅ 自动创建和更新 Gitea 发布
• ✅ 支持模板变量替换（版本号、变更日志等）
• ✅ 支持草稿和预发布版本
• ✅ 支持文件和文件夹附件上传
• ✅ 支持自动打包文件夹为 ZIP
• ✅ 支持通配符文件匹配

快速开始

1. 安装插件

npm install --save-dev release-it-gitea
# 或
pnpm add -D release-it-gitea
# 或
yarn add -D release-it-gitea

2. 设置环境变量

export GITEA_TOKEN="your-gitea-api-token"

3. 基础配置

在 .release-it.json 中添加：

{
	"plugins": {
		"release-it-gitea": {
			"host": "https://gitea.example.com",
			"owner": "your-username",
			"repository": "your-repo"
		}
	}
}

4. 运行发布

npx release-it

详细配置

基本配置选项

| 选项 | 类型 | 默认值 | 描述 | | -------------- | ----------------------------- | ---------------------- | -------------------------------------------------- | | host | string | 当前仓库的 host | Gitea 服务器 URL | | owner | string | 从 git remote 自动检测 | 仓库所有者 | | repository | string | 从 git remote 自动检测 | 仓库名称 | | release | boolean | true | 是否创建发布 | | releaseTitle | string | (context) => string | "v${version}" | 发布标题模板，支持变量替换和函数回调 | | releaseNotes | string | (context) => string | "${changelog}" | 发布说明模板，支持变量替换、Markdown格式和函数回调 | | prerelease | boolean | false | 是否为预发布 | | draft | boolean | false | 是否为草稿 | | tokenRef | string | "GITEA_TOKEN" | API token 环境变量名 | | timeout | number | 30000 | 请求超时时间（毫秒） | | assets | array | [] | 附加的资源文件 |

完整配置示例

{
	"plugins": {
		"release-it-gitea": {
			"host": "https://gitea.example.com",
			"owner": "your-username",
			"repository": "your-repo",
			"release": true,
			"releaseTitle": "Release ${version}",
			"releaseNotes": "## 更新内容\n\n${changelog}",
			"prerelease": false,
			"draft": false,
			"tokenRef": "GITEA_TOKEN",
			"timeout": 30000,
			"assets": [
				"dist/app.js",
				"README.md",
				{
					"path": "dist/**/*",
					"name": "distribution-file.zip",
					"type": "zip",
					"label": "Distribution Files"
				}
			]
		}
	}
}

插件间配置共享

mergeOptionsKeys 允许其他 release-it 插件动态设置本插件的配置项，实现插件间的配置共享和协作。

使用场景

当你有多个插件需要协同工作时，例如：

• 一个插件负责构建小程序，并需要将构建产物添加到 Gitea 发布的附件中
• 一个插件生成文档，并需要动态修改发布说明

配置方式

在 .release-it.json 中配置：

{
	"plugins": {
		"release-it-gitea": {
			"host": "https://gitea.example.com",
			"owner": "your-username",
			"repository": "your-repo",
			"assets": ["README.md"],
			"mergeOptionsKeys": ["assets", "releaseNotes"]
		}
	}
}

其他插件中设置配置

在其他 release-it 插件中，可以通过 setContext 方法动态设置配置：

// 在其他插件的某个生命周期方法中
class MyPlugin extends Plugin {
	async beforeRelease() {
		// 动态添加附件
		this.config.setContext({
			"release-it-gitea": {
				assets: ["dist/miniprogram.zip", "dist/source-map.zip"],
			},
		});
	}
}

合并规则

• 数组类型（如 assets）：上下文中的值会与配置文件中的值合并

  // 配置文件: ["README.md"]
  // 上下文设置: ["dist/app.zip"]
  // 最终结果: ["dist/app.zip", "README.md"]

• 非数组类型（如 releaseNotes）：上下文中的值会覆盖配置文件中的值

  // 配置文件: "默认发布说明"
  // 上下文设置: "自定义发布说明"
  // 最终结果: "自定义发布说明"

完整示例

假设你有一个小程序构建插件：

// release-it-miniprogram-plugin.js
import { Plugin } from "release-it";

class MiniprogramPlugin extends Plugin {
	async beforeRelease() {
		// 构建小程序
		await this.buildMiniprogram();

		// 将构建产物添加到 Gitea 发布
		this.config.setContext({
			"release-it-gitea": {
				assets: [
					"dist/miniprogram.zip",
					{
						path: "dist/source-map/**/*",
						name: "source-maps.zip",
						type: "zip",
					},
				],
			},
		});
	}

	async buildMiniprogram() {
		// 构建逻辑...
	}
}

export default MiniprogramPlugin;

配置文件：

{
	"plugins": {
		"release-it-miniprogram-plugin": {},
		"release-it-gitea": {
			"host": "https://gitea.example.com",
			"assets": ["README.md", "CHANGELOG.md"],
			"mergeOptionsKeys": ["assets"]
		}
	}
}

最终发布时会上传：

• dist/miniprogram.zip（来自小程序插件）
• source-maps.zip（来自小程序插件）
• README.md（来自配置文件）
• CHANGELOG.md（来自配置文件）

附件上传功能

基本用法

支持多种格式的附件配置：

{
	"assets": [
		"dist/app.js", // 单个文件
		"dist/**/*.min.js", // 通配符匹配
		"*.md" // 多个匹配文件
	]
}

高级配置

使用对象格式进行更详细的配置：

{
	"assets": [
		{
			"path": "dist/**/*",
			"name": "distribution-files.zip",
			"type": "zip",
			"label": "Distribution Files"
		},
		{
			"path": "docs/*.md",
			"type": "file",
			"label": "Documentation"
		},
		{
			"path": "src",
			"name": "source-code-file.zip",
			"type": "zip",
			"label": "Source Code"
		}
	]
}

附件配置参数

| 属性 | 类型 | 必需 | 描述 | | ------- | --------------- | ---- | ------------------------------------ | | path | string | ✅ | 文件或文件夹路径，支持通配符 | | name | string | ❌ | 上传后的文件名，不指定则使用原文件名 | | type | 'file' | 'zip' | ❌ | 文件类型，默认为 'file' | | label | string | ❌ | 文件标签，用于标识文件用途 |

文件类型说明

• file: 直接上传匹配到的文件
• zip: 将匹配到的文件打包成 ZIP 文件后上传

使用场景示例

场景 1：上传构建产物

{
	"assets": ["dist/bundle.js", "dist/bundle.css", "dist/assets/**/*"]
}

场景 2：打包源代码发布

{
	"assets": [
		{
			"path": "src/**/*",
			"name": "source-vfile.zip",
			"type": "zip",
			"label": "Source Code"
		}
	]
}

场景 3：多种文件类型组合

{
	"assets": [
		"README.md",
		"CHANGELOG.md",
		{
			"path": "dist",
			"name": "build-output.zip",
			"type": "zip"
		},
		{
			"path": "docs/**/*.pdf",
			"type": "file",
			"label": "Documentation"
		}
	]
}

场景 4：不同环境的配置

{
	"assets": [
		{
			"path": "dist/prod/**/*",
			"name": "production-build-file.zip",
			"type": "zip",
			"label": "Production Build"
		},
		{
			"path": "dist/dev/**/*",
			"name": "development-build-file.zip",
			"type": "zip",
			"label": "Development Build"
		}
	]
}

环境变量配置

默认 Token 配置

export GITEA_TOKEN=your_gitea_api_token

自定义 Token 配置

{
	"tokenRef": "MY_GITEA_TOKEN"
}

export MY_GITEA_TOKEN=your_gitea_api_token

模板变量

在 releaseTitle 和 releaseNotes 中可以使用以下变量：

| 变量 | 描述 | 示例 | | -------------------- | ------------ | -------------------- | | ${version} | 当前版本号 | 1.2.3 | | ${latestVersion} | 上一个版本号 | 1.2.2 | | ${changelog} | 变更日志 | - 修复了某个bug | | ${name} | 项目名称 | my-awesome-project | | ${repo.owner} | 仓库所有者 | username | | ${repo.repository} | 仓库名称 | my-repo | | ${branchName} | 分支名称 | main |

函数回调配置

在 JavaScript 配置文件中，可以为 releaseTitle 和 releaseNotes 传入函数回调，实现更灵活的配置：

// .release-it.js
module.exports = {
	plugins: {
		"release-it-gitea": {
			host: "https://gitea.example.com",
			owner: "your-username",
			repository: "your-repo",
			// 使用函数生成动态的发布标题
			releaseTitle: (context) => {
				const date = new Date().toISOString().split("T")[0];
				return `🚀 ${context.name} v${context.version} (${date})`;
			},
			// 使用函数生成动态的发布说明
			releaseNotes: (context) => {
				const sections = context.changelog.split("\n## ");
				const features = sections.find(
					(s) => s.startsWith("Features") || s.startsWith("新特性"),
				);
				const fixes = sections.find(
					(s) => s.startsWith("Bug Fixes") || s.startsWith("修复"),
				);

				return `## ${context.name} v${context.version} 发布说明
        
## ✨ 新特性
${features ? "## " + features : "无"}

## 🐛 问题修复
${fixes ? "## " + fixes : "无"}

## 📦 安装
\`\`\`
npm install ${context.name}@${context.version}
\`\`\``;
			},
			// 其他配置...
		},
	},
};

使用函数回调的优势：

• 可以进行复杂的逻辑处理
• 可以访问完整的 context 对象
• 可以根据条件动态生成内容
• 可以整合外部数据或API结果

注意: 函数回调仅在使用 JavaScript 配置文件 (如 .release-it.js 或 .release-it.cjs) 时可用，在 JSON 配置文件中只能使用字符串模板。

使用 NPM 包

releaseTitle 和 releaseNotes 还支持通过 npm: 前缀引用外部 NPM 包来生成内容：

{
	"plugins": {
		"release-it-gitea": {
			"releaseTitle": "npm:my-release-notes-generator",
			"releaseNotes": "npm:my-changelog-formatter"
		}
	}
}

使用 NPM 包的方式：

1. 创建并发布一个 NPM 包，该包导出以下方法：

   // my-release-notes-generator 包示例
   module.exports = {
   	releaseTitle: function (context) {
   		return `Release v${context.version} - ${new Date().toLocaleDateString()}`;
   	},
   	releaseNotes: function (context) {
   		// 自定义格式化逻辑
   		return `# ${context.name} v${context.version}\n\n${context.changelog}`;
   	},
   };

2. 安装该包：

   npm install --save-dev my-release-notes-generator

3. 在配置中引用：

   {
   	"releaseTitle": "npm:my-release-notes-generator",
   	"releaseNotes": "npm:my-release-notes-generator"
   }

使用 NPM 包的优势：

• 可以在多个项目间共享相同的发布标题和说明格式
• 可以独立于项目维护和更新发布格式
• 支持更复杂的逻辑和依赖
• 可以在 JSON 配置中使用，不仅限于 JavaScript 配置

Context 对象属性

在函数回调中，您可以访问以下 context 对象属性：

| 属性 | 类型 | 描述 | 示例值 | | ----------------- | ------ | ----------------------------- | -------------------------------- | | version | string | 当前版本号 | "1.2.3" | | latestVersion | string | 上一个版本号 | "1.2.2" | | changelog | string | 生成的变更日志内容 | "## Bug Fixes\n\n* 修复..." | | name | string | 项目名称 | "my-project" | | branchName | string | 当前分支名 | "main" | | releaseUrl | string | 发布 URL (仅在更新发布后可用) | "https://gitea.com/.../v1.2.3" | | repo | object | 仓库相关信息 | | | repo.host | string | 仓库主机地址 | "gitea.example.com" | | repo.owner | string | 仓库所有者 | "username" | | repo.project | string | 项目名称 | "my-repo" | | repo.protocol | string | 仓库协议 | "https" | | repo.remote | string | 远程仓库名称 | "origin" | | repo.repository | string | 仓库名称 | "my-repo" |

示例：使用 context 属性生成自定义发布标题

releaseTitle: (context) => {
	const emoji = context.version.includes("beta")
		? "🧪"
		: context.version.includes("alpha")
			? "🚧"
			: "🚀";
	return `${emoji} ${context.name} v${context.version} [${context.branchName}]`;
};

模板使用示例

{
	"releaseTitle": "🚀 ${name} v${version}",
	"releaseNotes": "## 📋 更新内容\n\n${changelog}\n\n## 📦 下载\n\n请下载对应平台的文件",
	"assets": [
		{
			"path": "dist/**/*",
			"name": "distribution-files.zip",
			"type": "zip",
			"label": "Distribution Files"
		}
	]
}

注意: 附件配置中的 name 和 label 字段不支持模板变量替换，需要使用静态字符串。

故障排除

常见问题及解决方案

1. 附件上传失败

问题症状：

• 附件上传时出现错误
• 文件找不到

解决方案：

• 检查文件路径是否正确
• 确保文件存在且可读
• 检查 Gitea API Token 权限是否包含附件上传权限

2. ZIP 文件创建失败

问题症状：

• ZIP 文件创建时出错
• 磁盘空间不足错误

解决方案：

• 确保有足够的磁盘空间
• 检查临时目录权限
• 验证要打包的文件是否存在

3. 通配符匹配无文件

问题症状：

• 通配符模式没有匹配到任何文件
• 附件列表为空

解决方案：

• 验证通配符模式是否正确
• 检查当前工作目录
• 使用绝对路径或相对路径进行测试

4. API 请求失败

问题症状：

• 401 未授权错误
• 404 仓库不存在错误
• 网络超时

解决方案：

• 检查 Gitea 服务器地址是否正确
• 验证 API Token 是否有效且未过期
• 确认仓库所有者和名称正确
• 检查网络连接和防火墙设置

调试技巧

启用详细日志

npx release-it --verbose

使用干运行模式

npx release-it --dry-run

检查配置

npx release-it --config --verbose

开发指南

开发环境搭建

# 克隆仓库
git clone https://github.com/lib-pack/release-it-gitea.git
cd release-it-gitea

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 格式化代码
pnpm format

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE.md 文件。

致谢

感谢所有为这个项目做出贡献的开发者！

如果您觉得这个项目对您有帮助，请给我们一个 ⭐️！