# Gradle 预览

直接从 Gradle 构建并分享 Android 应用和原生命令行工具。首先阅读<.localized_link href="/guides/get-started/gradle-project">Gradle 项目指南</.localized_link>，以连接项目并进行身份验证。

## Android 应用

```bash
./gradlew :app:tuistShareDebug
```

`dev.tuist` 设置插件会为 Android Gradle Plugin（8.8.2 或更高版本）中的每个应用变体注册一个`tuistShare<Variant>`任务。将`app`和`Debug`替换为你的应用模块和变体，例如针对产品风味的`:app:tuistShareDemoDebug`。该任务在发布之前通过 Gradle 声明的构件依赖项构建 APK。当构建输出已是最新状态或从构建缓存中恢复时，它也能正常工作。

仅支持单个已签名的通用应用 APK。Android 的 debug 变体通常使用调试签名密钥；release 变体需要你自己的签名配置。该任务会在身份验证或上传之前验证 APK 签名。未签名、无效、instrumentation 以及拆分 APK 会被拒绝。库模块、测试 APK 和 Android App Bundle（`.aab`）不是发布目标。

## 原生命令行工具

使用 Gradle 的`cpp-application`或`swift-application`插件的项目会为每个原生二进制文件获得一个分享任务：

```bash
./gradlew :app:tuistShareMainDebug
```

该任务会构建并打包已安装的分发内容，包括其启动器和运行时库。对 release 二进制文件使用`tuistShareMainRelease`。面向多台机器的项目会为每个二进制文件提供一个任务；运行`./gradlew :app:tasks --all`以查找它们的名称。

支持 arm64 或 x86_64 的原生 macOS 和 Linux 可执行文件。在目标平台上使用 Gradle 插件所需的工具链进行构建。此集成不支持 JVM 应用及其生成的启动器脚本。

## 发布行为

分享任务使用插件现有的 Tuist 凭据进行发布，无需调用 Tuist CLI。普通的`assemble`、`build`和测试任务永远不会发布预览。

分享后，在项目中打开**预览**以复制链接。重复分享相同的构建和轨道会复用其发布，包括在构建缓存命中之后。失败或未确认的上传会导致分享任务失败；它们不会被报告为成功的预览。

## CI 和轨道

使用与插件其他需要身份验证的功能相同的凭据配置<.localized_link href="/guides/integrations/continuous-integration">CI 身份验证</.localized_link>，然后显式请求发布：

```bash
./gradlew :app:tuistShareDebug --track nightly
```

以相同方式将`--track nightly`添加到原生分享任务。任务会使用配置的 Tuist 项目、服务器 URL 和代理设置。预览发布始终需要身份验证。这些任务不会附加 Git 修订元数据、发布说明或自动拉取请求评论。

在托管的 Tuist 上，构件发布会在 30 天后过期。自托管实例使用`TUIST_APP_PREVIEW_RETENTION_DAYS`；不设置该项将禁用此系列发布的过期。过期的发布无法通过重复相同的操作来恢复。

## 分享现有 APK

对于在此工作流之外构建的 APK，或者为了在使用传统上传流程时包含发布说明，CLI 仍然可用：

```bash
tuist share app/build/outputs/apk/debug/app-debug.apk \
  --track nightly --release-notes "Improve checkout"
```

请参阅<.localized_link href="/guides/features/previews#run-a-preview">运行预览</.localized_link>，了解如何运行已发布的构建、访问权限、轨道以及 README 徽章。

## 使用 tuist share 进行渠道管理 {#share-tracks}

对于使用 `tuist share` 发布的工作流，请使用 `--track` 选择渠道：

```bash
tuist share App --track beta
tuist share App --track nightly
```

## 发布说明 {#release-notes}

使用渠道区分环境组，并使用发布说明标识单个构建的用途：

```bash
tuist share App --track QA --release-notes "Fix sign-in and improve the checkout flow"
```

将 `App` 替换为你的应用名称、应用文件路径或可执行分发项及其 `--executable` 选项。发布说明为可选纯文本，最多 10,000 个字符。首个非空行会在预览列表中以单行摘要形式显示，因此构建编号和其他识别信息一目了然。长行会被截断；完整说明会显示在详情页面中。搜索匹配会覆盖显示名称和完整发布说明，包括未在摘要中显示的行。支持多行说明，例如 `--release-notes "$(< release-notes.txt)"`。它们不会更改应用的显示名称或其所属渠道。

### 兼容性 {#preview-metadata-compatibility}

发布说明不会改变构建所属的预览。预览接收的首条说明会被保留：后续上传可以为尚无说明的预览添加说明，但无法覆盖或清除现有说明。在发布说明功能推出之前上传的预览仍然有效，无需补充说明。

自托管部署需要支持发布说明和渠道过滤的服务器版本，以及更新的客户端。旧版服务器会忽略这些说明。有关列表端点的渠道和搜索过滤器，请参阅 [API 参考](https://tuist.dev/api/docs)。

## 拉取请求/合并请求评论 {#pullmerge-request-comments}

> [!WARNING]
> **需要集成 Git 代码托管平台**
>
> 要获取自动化的拉取请求/合并请求评论，请将你的 <.localized_link href="/guides/server/accounts-and-projects">远程项目</.localized_link> 与 Git 代码托管平台集成：<.localized_link href="/guides/integrations/gitforge/github">GitHub</.localized_link>、<.localized_link href="/guides/integrations/gitforge/origin">Cursor Origin</.localized_link> 或 <.localized_link href="/guides/integrations/gitforge/entire">Entire</.localized_link>。

当你的 Tuist 项目与 Git 平台连接后，在 CI 中成功构建应用后添加 <.localized_link href="/cli/share">`tuist share`</.localized_link>。Tuist 会直接在拉取请求/合并请求中发布预览链接，以便评审者无需在本地构建即可测试：

![带有 Tuist Preview 链接的 GitHub 应用评论](/images/guides/features/github-app-with-preview.png)

## 自动化 {#automations}

使用 `--json` 从 `tuist share` 获取 JSON 输出：

```bash
tuist share --json
```

将结果用于自定义自动化，例如从 CI 发布 Slack 消息。`url` 键包含完整的预览链接；`qrCodeURL` 指向用于在设备上打开预览的二维码图片：

```json
{
  "id": 1234567890,
  "url": "https://tuist.dev/preview/1234567890",
  "qrCodeURL": "https://tuist.dev/preview/1234567890/qr-code.svg"
}
```

